#

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.10.3/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.