The Recordset utility allows the storage and retrieval of objects with similar properties.

Using Recordsets

Recordset basics

A Recordset in its simplest form is a collection of records, where records can be considered to be object literals. Recordset allows the user to handle this collection of records with a consistent API.

Recordset augments the functionality of Y.Arraylist but goes a step further, by allowing the developer to quickly store and retrieve objects with similar properties. Additional submodules can be plugged into a Y.Recordset instance to enable sorting, filtering and indexing by specific keys.

Initializing a Recordset is straight-forward:

``` YUI().use("recordset-base", function(Y) { var data = [ {a:3, b:2, c:1}, {a:9, b:8, c:7}, {a:1, b:2, c:3} ], //Recordset is created with the objects from the data array myRecordset = new Y.Recordset({records: data}), //Empty Recordsets can also be created anEmptyRecordset = new Y.Recordset(); }); ```

Adding, Removing, Updating and Emptying

A Y.Recordset can be filled with a single, or an array of object literals. Under the hood, Recordset will convert these objects into record instances - essentially creating a light wrapper around them.

More information on performing operations on Recordset can be seen the the documentation for the recordset-base sub-module.

Adding Records

``` var data = [ {key:"a", label:"Column A"}, {key:"b", label:"Column B"}, {key:"c", label:"Column C"} ], myRecordset = new Y.Recordset({records:data}); //Adding a single record to the end of a Recordset myRecordset.add({key:"d", label:"Column D"}); //Adding multiple records at the 2nd index of the Recordset myRecordset.add([ {key:"e", label:"Column E"}, {key:"f", label:"Column F"} ], 2); ```

Removing Records

``` var data = [ {key:"a", label:"Column A"}, {key:"b", label:"Column B"}, {key:"c", label:"Column C"} ], myRecordset = new Y.Recordset({records:data}); //removes the record stored at index 2 (in this case {key:"c", label:"Column C"} is removed) myRecordset.remove(2); //Removes 2 records starting at index zero myRecordset.remove(0,2); ```

Updating Records

``` var data = [ {key:"a", label:"Column A"}, {key:"b", label:"Column B"}, {key:"c", label:"Column C"} ], myRecordset = new Y.Recordset({records:data}); //overwite the record at index 2 with the following record myRecordset.update({key:"d", label:"Column D"}, 2); //You can also update multiple records at a time. //Here we are updating indices 0 and 1 of the Recordset with the corresponding two objects. myRecordset.update([ {key:"e", label:"Column E"}, {key: "f", label: "Column F"} ], 0); ```

Emptying a Recordset

``` var data = [ {key:"a", label:"Column A"}, {key:"b", label:"Column B"}, {key:"c", label:"Column C"} ], myRecordset = new Y.Recordset({records:data}); myRecordset.empty(); ```

Events

The Recordset Utility fires custom events in addition attribute change events. Details on these events are shown below. The sub-module responsible for firing each event is represented in square braces.

Event [sub-module]	Payload
`add` [base]	added: an array of new records that were added (can contain a single record) index: index that the addition started at
`remove` [base]	removed: an array of records that were removed (can contain a single record) index: index that the removals started at range: range of records that were removed
`update` [base]	updated: an array of records that updated (added to the Recordset) index: index that the updates started at range: range of records that were updated
`empty` [base]	Empty object bag
`change` [base]	Empty object bag, fired whenever records in the Recordset change (ie: they are added, removed, updated, or emptied)
`sort` [sort]	field: A string representing the key to sort by desc: Boolean representing whether sorting order is descending sorter: The comparison function being used to sort

Sorting

The RecordsetSort plugin allows a Recordset to have default and custom sorting functionality. Various helper methods and attributes are provided. A brief listing is shown below. Refer to the documentation for the RecordsetSort plugin to see code snippets.

sort(key,desc,function [optional]): Sorts a Recordset by the value in the provided key. Recordset is sorted in descending order if desc is truthy. Optional custom comparison function can be supplied to sort by.
resort(): Resorts a Recordset using last-used sorting arguments
reverse(): Reverses the Recordset without performing any sort operations
flip(): Resorts the Recordset in ascending order if the last sort arguments specified descending, and vice versa.
lastSortProperties Attribute: An object bag with field, desc and sorter keys listing the last-used arguments to sort by.
isSorted Attribute: A boolean representing if the Recordset is in a sorted state.

Filtering

The RecordsetFilter plugin allows a Recordset to be filtered, and returns subsets of that Recordset (as a separate Recordset instance). Refer to the documentation for the RecordsetFilter plugin to see code snippets.

filter(key or function, value): If a key/value pair is passed in, returns a Recordset with records that match the key/value pair. Supports a custom function for more advanced filtering. The custom function must return a boolean.
reject(function): The inverse of filter. Executes the supplied function on each item. Returns a new Recordset containing the items that the supplied function returned false for.
grep(pattern): Iterates over the Recordset, returning a new Recordset of all the elements that match the supplied regular expression

Indexing

In the recordset-base submodule, the table attribute stores an associative array that hashes all records within the Recordset by their unique YUIDs. This table is kept in sync with the Recordset through custom events.

To allow for customization when indexing, there is the RecordsetIndexer plugin. Refer to the RecordsetIndexer documentation for full details.

createTable(key): Creates a hash table with the given key with all existing records in the Recordset.
getTable(key): Get a hash table that hashes records by a given key.
hashTables attribute: An object bag, with each property referring to a user-created hash table.