2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<style scoped>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly/* custom styles for this example */
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly#htContainer {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly font-size:90%;
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<div class="intro">
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith <p>The RecordsetIndexer plugin provides the ability to define custom hash tables to a Recordset instance.</p>
819e90d415ed17d59af3a247b2ad9d6feb0c21b5Luke Smith<div class="example yui3-skin-sam">
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly{{>recordset-indexer-source}}
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<p>The Indexer plugin allows a user to create custom hash tables for a Recordset instance.</p>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h3>Using the Plugin</h3>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<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>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", "recordset-indexer", function(Y) {
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Add "recordset-indexer" sub-module in the use statement.
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});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //Plugging in Sorting functionality
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //You can now call methods to allow for custom hash tables on the myRecordset instance using the "indexer" namespace.
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h3>Using the RecordsetIndexer Plugin</h3>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<ul class="topspace">
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#create">Creating a Hash Table</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#access">Accessing Hash Tables</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#crud">Performing Standard Operations</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly <li><a href="#collisions">Collision Handling</a></li>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="create">Creating a Hash Table</h4>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<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>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base","recordset-indexer", 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});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //creates and returns a new hash table which indexes by the key 'a'
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly var tableA = myRecordset.indexer.createTable('a');
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //calling tableA[9] would return a record instance of {a:9, b:8, c:7}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //calling tableA[3].getValue() would return {a:3, b:2, c:1}
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //calling tableA[10] would return undefined
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="access">Accessing Tables</h4>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<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>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny DonnellyYUI().use("recordset-base", "recordset-indexer", 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});
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //create two hash tables
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly var hashA = myRecordset.indexer.createTable('a'),
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //get access to the hashtable object
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly hashTables = myRecordset.indexer.get('hashTables');
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly //we can access the 2nd hash table we created through the object
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="crud">Performing Standard Operations</h4>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<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>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<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>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<h4 id="crud">Collision Handling</h4>
2ae838b915a73181e0b6e18715d67cfeb5c21b62Jenny Donnelly<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>
125a6c5e5913a2ffbc0e4589e241c7e868e6e0deLuke Smith<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>