2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<div class="intro">
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <p>The Recordset Utility provides a standard way for dealing with a collection of similar objects known as records. The `recordset-base` sub-module provides the base Recordset implementation.<p>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <p>This example demonstrates some standard ways to interact with the Recordset. Click on the buttons below to play around with a Recordset created with state information.</p>
819e90d415ed17d59af3a247b2ad9d6feb0c21b5Luke Smith<div class="example yui3-skin-sam">
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly{{>recordset-basic-source}}
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>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.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<p>Recordset-base provides an API for adding, removing and updating record(s). It also creates a hash table of all the records by their IDs, to allow for fast retrieval.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h6>Records vs. Object Literals</h6>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>You can interact with a Recordset instance by simply passing in object literals. Recordset will convert them into record instances under the hood. If you want the object literal back from the Recordset, simply use the `getValue` method on a record instance. Optionally, a string can be passed into the `getValue` method if you only want a specific property back. Not passing in an argument returns the entire object bag that the record is holding on to.
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h3>Working with a Recordset</h3>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyThis section describes how to use the Recordset Utility in further detail. It contains the following subsections:
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<ul class="topspace">
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#instantiation">Initializing a Recordset</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#adding">Adding Records</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#removing">Removing Records</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#updating">Updating Records</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#emptying">Emptying a Recordset</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#hash">Using the Hash Table</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="instantiation">Initializing a Recordset</h4>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {a:3, b:2, c:1},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {a:9, b:8, c:7},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {a:1, b:2, c:3}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Recordset is created with the objects from the data array
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset = new Y.Recordset({records: data}),
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith //Empty Recordsets can also be created
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly anEmptyRecordset = new Y.Recordset();
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="adding">Adding Records</h4>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>Once initialized, the Recordset can be modified by CRUD methods provided by the API. Add single or multiple objects/records to the Recordset by calling the `add` method.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordst-base", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"a", label:"Column A"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"b", label:"Column B"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"c", label:"Column C"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset = new Y.Recordset({records:data});
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith //Adding a single record to the end of a Recordset
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset.add({key:"d", label:"Column D"});
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith //Adding multiple records at the 2nd index of the Recordset
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"e", label:"Column E"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"f", label:"Column F"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="removing">Removing Records</h4>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>Similarly, items can also be removed from the Recordset using the `remove` method.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"a", label:"Column A"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"b", label:"Column B"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"c", label:"Column C"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset = new Y.Recordset({records:data});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //removes the record stored at index 2 (in this case {key:"c", label:"Column C"} is removed)
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Removes 2 records starting at index zero
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="updating">Updating Records</h4>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>You can overwrite existing records in the Recordset through the `update` method. This method takes 2 arguments, the first being an object/record or array of objects/records, and the second being the index at which to start the update process. When updating a Recordset, any records found within the index/indices that are to be updated will be overwritten. However, you can get an object bag with these overwritten records back if you hook onto the 'update' event. </p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"a", label:"Column A"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"b", label:"Column B"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"c", label:"Column C"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset = new Y.Recordset({records:data});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //overwite the record at index 2 with the following record
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset.update({key:"d", label:"Column D"}, 2);
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //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.
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"e", label:"Column E"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key: "f", label: "Column F"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="emptying">Emptying a Recordset</h4>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>Emptying the Recordset is easily done with the `empty` method. </p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"a", label:"Column A"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"b", label:"Column B"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"c", label:"Column C"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset = new Y.Recordset({records:data});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="hash">Using the Hash Table</h4>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<p>The recordset-base submodule has a built-in hash table that hashes records by their IDs. IDs are set during initialization of each individual record and are stored as ATTRS. You should not modify the ID of a record, but you can access it by calling `myRecord.get('id')`.</p>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>Under the hood, the hash table is kept in sync with the Recordset by hooking onto the events that Recordset fires (namely 'add', 'remove', 'update', and 'empty'). The ID hash table is an easy way to retrieve records that will be needed often.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<p>If you need hash tables that store records by keys other than IDs, refer to the <strong>RecordsetIndexer</strong> plugin.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"a", label:"Column A"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"b", label:"Column B"},
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly {key:"c", label:"Column C"}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly myRecordset = new Y.Recordset({records:data});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Store some IDs that I will need access to later
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly var record2_ID = myRecordset.getRecord(1).get('id'),
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly record3_ID = myRecordset.getRecord(2).get('id');
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Get Access to the Hash Table
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly var hashTable = myRecordset.get('table');
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Get Records back using IDs
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly var record2 = hashTable[record2_ID];
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly var record3 = hashTable[record3_ID];
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Remove Record from index 1 (record2)
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly hashTable[record2_ID]; //this will now be undefined as that record was removed.
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly hashTable[record3_ID]; //this still points to the correct record (record3)
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h3>Events</h3>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>The Recordset Utility fires 5 custom events in addition attribute change events: <strong>'add'</strong>, <strong>'remove'</strong>, <strong>'update'</strong>, <strong>'empty'</strong> and <strong>'change'</strong>. <strong>'change'</strong> in particular, is a high-level event that is fired after any modifications to the Recordset are made (ie: after 'add', 'remove', 'update', 'empty'). Details on these events are shown below.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <th>Event</th>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <th>Payload</th>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td>`add`</td>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td><strong>added:</strong> an array of new records that were added (can contain a single record)<br/>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <strong>index:</strong> index that the addition started at
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td>`remove`</td>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td><strong>removed:</strong> an array of records that were removed (can contain a single record)<br/>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <strong>index:</strong> index that the removals started at<br/>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <strong>range:</strong> range of records that were removed
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td>`update` </td>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <td><strong>updated:</strong> an array of records that updated (added to the Recordset)<br/>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <strong>index:</strong> index that the updates started at<br/>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <strong>range:</strong> range of records that were updated
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td>`empty`</td>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td>Empty object bag</td>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td>`change`</td>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <td><strong>type:</strong> The event that caused the change (ie: "recordset:add", "recordset:update")<br/>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <strong>details:</strong>The payload of the event that caused the change. This object will have different keys, based on what `type` is. (ie: If `type` is "recordset:add", then `details` will contain the `added` and `index` keys.)<br/>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>Refer to the API documentation to get a full list of events inherited by Recordset.</p>