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