daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<div class="intro component">
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The Recordset utility allows the storage and retrieval of objects with
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith similar properties.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith{{>getting-started}}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="using">Using Recordsets</h2>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="basics">Recordset basics</h3>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith A Recordset in its simplest form is a collection of records, where records
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith can be considered to be object literals. Recordset allows the user to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith handle this collection of records with a consistent API.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Recordset augments the functionality of <code>Y.Arraylist</code> but goes a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith step further, by allowing the developer to quickly store and retrieve
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith objects with similar properties. Additional submodules can be plugged into
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith a <code>Y.Recordset</code> instance to enable sorting, filtering and
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith indexing by specific keys.
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith Initializing a Recordset is straight-forward:
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithYUI().use("recordset-base", function(Y) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith var data = [
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {a:3, b:2, c:1},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {a:9, b:8, c:7},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {a:1, b:2, c:3}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith //Recordset is created with the objects from the data array
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith myRecordset = new Y.Recordset({records: data}),
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith //Empty Recordsets can also be created
582a591f82aa3dd9805fa3efff15576d3063711cEric Ferraiuolo anEmptyRecordset = new Y.Recordset();
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="crud">Adding, Removing, Updating and Emptying</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith A <code>Y.Recordset</code> can be filled with a single, or an array of
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith object literals. Under the hood, Recordset will convert these objects into
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>record</code> instances - essentially creating a light wrapper around
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith More information on performing operations on Recordset can be seen the the
582a591f82aa3dd9805fa3efff15576d3063711cEric Ferraiuolo documentation for the <a href="recordset-basic.html">
582a591f82aa3dd9805fa3efff15576d3063711cEric Ferraiuolo <code>recordset-base</code> sub-module</a>.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="add">Adding Records</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"a", label:"Column A"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"b", label:"Column B"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"c", label:"Column C"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyRecordset = new Y.Recordset({records:data});
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith//Adding a single record to the end of a Recordset
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyRecordset.add({key:"d", label:"Column D"});
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith//Adding multiple records at the 2nd index of the Recordset
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"e", label:"Column E"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"f", label:"Column F"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="remove">Removing Records</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"a", label:"Column A"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"b", label:"Column B"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"c", label:"Column C"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyRecordset = new Y.Recordset({records:data});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith//removes the record stored at index 2 (in this case {key:"c", label:"Column C"} is removed)
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith//Removes 2 records starting at index zero
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4>Updating Records</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"a", label:"Column A"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"b", label:"Column B"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"c", label:"Column C"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyRecordset = new Y.Recordset({records:data});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith//overwite the record at index 2 with the following record
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyRecordset.update({key:"d", label:"Column D"}, 2);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith//You can also update multiple records at a time.
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith//Here we are updating indices 0 and 1 of the Recordset with the corresponding two objects.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"e", label:"Column E"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key: "f", label: "Column F"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4>Emptying a Recordset</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"a", label:"Column A"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"b", label:"Column B"},
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith {key:"c", label:"Column C"}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyRecordset = new Y.Recordset({records:data});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="events">Events</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The Recordset Utility fires custom events in addition attribute change
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith events. Details on these events are shown below. The sub-module responsible
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith for firing each event is represented in square braces.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Event [sub-module]</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Payload</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>add</code> [base]</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><strong>added:</strong> an array of new records that were added (can contain a single record)<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>index:</strong> index that the addition started at
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>remove</code> [base]</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><strong>removed:</strong> an array of records that were removed (can contain a single record)<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>index:</strong> index that the removals started at<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>range:</strong> range of records that were removed
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>update</code> [base]</td>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <td><strong>updated:</strong> an array of records that updated (added to the Recordset)<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>index:</strong> index that the updates started at<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>range:</strong> range of records that were updated
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>empty</code> [base]</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>Empty object bag</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>change</code> [base]</td>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <td>Empty object bag, fired whenever records in the Recordset change (ie: they are added, removed, updated, or emptied)</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>sort</code> [sort]</td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><strong>field:</strong> A string representing the key to sort by<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>desc:</strong> Boolean representing whether sorting order is descending<br/>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>sorter:</strong> The comparison function being used to sort
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="sorting">Sorting</h3>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith The <code>RecordsetSort</code> plugin allows a Recordset to have default
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith and custom sorting functionality. Various helper methods and attributes are
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith provided. A brief listing is shown below. Refer to the documentation for
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>RecordsetSort</code> plugin</a> to see code snippets.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>sort(key,desc,function [optional])</code></dt>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith Sorts a Recordset by the value in the provided key. Recordset is
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith sorted in descending order if <code>desc</code> is truthy. Optional
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith custom comparison function can be supplied to sort by.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>resort()</code></dt>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <dd>Resorts a Recordset using last-used sorting arguments</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>reverse()</code></dt>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <dd>Reverses the Recordset without performing any sort operations</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>flip()</code></dt>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith Resorts the Recordset in ascending order if the last sort arguments
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith specified descending, and vice versa.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>lastSortProperties Attribute</code></dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith An object bag with <code>field</code>, <code>desc</code> and
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>sorter</code> keys listing the last-used arguments to sort
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>isSorted Attribute</code></dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dd>A boolean representing if the Recordset is in a sorted state.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="filtering">Filtering</h3>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith The <code>RecordsetFilter</code> plugin allows a Recordset to be filtered,
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith and returns subsets of that Recordset (as a separate Recordset instance).
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Refer to the documentation for the <a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>RecordsetFilter</code> plugin to see code snippets.</a>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>filter(key or function, value)</code></dt>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith If a key/value pair is passed in, returns a Recordset with records
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith that match the key/value pair. Supports a custom function for more
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith advanced filtering. The custom function must return a boolean.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>reject(function)</code></dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The inverse of filter. Executes the supplied function on each item.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Returns a new Recordset containing the items that the supplied
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith function returned <code>false</code> for.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>grep(pattern)</code></dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Iterates over the Recordset, returning a new Recordset of all the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith elements that match the supplied regular expression
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="indexing">Indexing</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith In the <code>recordset-base</code> submodule, the <code>table</code>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith attribute stores an associative array that hashes all records within the
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith Recordset by their unique YUIDs. This table is kept in sync with the
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith Recordset through custom events.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith To allow for customization when indexing, there is the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>RecordsetIndexer</code> plugin. Refer to the <a
582a591f82aa3dd9805fa3efff15576d3063711cEric Ferraiuolo href="recordset-indexer.html"><code>RecordsetIndexer</code>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith documentation</a> for full details.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>createTable(key)</code></dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Creates a hash table with the given key with all existing records
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith in the Recordset.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>getTable(key)</code></dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dd>Get a hash table that hashes records by a given key.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <dt><code>hashTables</code> attribute</dt>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith An object bag, with each property referring to a user-created hash