Jump to Table of Contents

Recordset

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

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.

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.