recordset-indexer.mustache revision 819e90d415ed17d59af3a247b2ad9d6feb0c21b5
<style scoped>
/* custom styles for this example */
#htContainer {
font-size:90%;
}
</style>
<div class="intro">
<p>The RecordsetIndexer plugin provides the ability to define custom hash tables to a Recordset instance.</p>
</div>
<div class="example yui3-skin-sam">
{{>recordset-indexer-source}}
</div>
<p>The Indexer plugin allows a user to create custom hash tables for a Recordset instance.</p>
<h3>Using the Plugin</h3>
<p>The RecordsetIndexer plugin can be "plugged in" to any Recordset instance using the `plug` method. Methods that exist on the plugin can be called using the <em>indexer</em> namespace</p>
```
YUI().use("recordset-base", "recordset-indexer", function(Y) {
//Add "recordset-indexer" sub-module in the use statement.
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});
//Plugging in Sorting functionality
//You can now call methods to allow for custom hash tables on the myRecordset instance using the "indexer" namespace.
});
```
<h3>Using the RecordsetIndexer Plugin</h3>
<ul class="topspace">
<li><a href="#create">Creating a Hash Table</a></li>
<li><a href="#access">Accessing Hash Tables</a></li>
<li><a href="#crud">Performing Standard Operations</a></li>
<li><a href="#collisions">Collision Handling</a></li>
</ul>
<h4 id="create">Creating a Hash Table</h4>
<p>The RecordsetIndexer plugin currently supports creating and accessing stored tables. Creating a new hash table is straightforward and is done through the `createTable` method. The only argument to be passed in is a string representing the key that should be used.</p>
```
YUI().use("recordset-base","recordset-indexer", 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});
//creates and returns a new hash table which indexes by the key 'a'
var tableA = myRecordset.indexer.createTable('a');
//calling tableA[9] would return a record instance of {a:9, b:8, c:7}
//calling tableA[3].getValue() would return {a:3, b:2, c:1}
//calling tableA[10] would return undefined
});
```
<h4 id="access">Accessing Tables</h4>
<p>All hash tables are stored under the `hashTables` attribute in RecordsetIndexer. This attribute is an object literal of all hash tables that are created. You can access the object through `myRecordset.indexer.get('hashTables')`. Specific hash tables can be accessed by appending their key names to the end (`myRecordset.indexer.get('hashTables').city`).</p>
```
YUI().use("recordset-base", "recordset-indexer", 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});
//create two hash tables
var hashA = myRecordset.indexer.createTable('a'),
//get access to the hashtable object
hashTables = myRecordset.indexer.get('hashTables');
//we can access the 2nd hash table we created through the object
hashC = hashTables.c;
});
```
<h4 id="crud">Performing Standard Operations</h4>
<p>Once hash tables have been created, they are kept in sync with the Recordset through the custom events that are fired: "add", "remove", "update" and "empty".</p>
<p>As a result, standard operations can be performed in the same way without worrying about the state of various hash tables. If a record is removed from the Recordset, the corresponding key in the hash table is deleted from the array entirely.</p>
<h4 id="crud">Collision Handling</h4>
<p>The RecordsetIndexer plugin does not have collision handling built in to it currently. As a result, if your hash table relates keys to records using a key that is non-unique, the last record encountered with the non-unique key will overwrite previous records. </p>
<p>Since all records are guaranteed to have a unique YUID, it is suggested to use the YUID as a key when using hash tables. Doing this does not require the RecordsetIndexer plugin at all since the base Recordset module already provides a hash table that stores records by their YUIDs.</p>