Getting Started

To include the source files for Recordset and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('recordset', function (Y) {
    // Recordset is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

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.

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.