The Indexer plugin allows a user to create custom hash tables for a Recordset instance.

Using the Plugin

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 indexer namespace

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
	myRecordset.plug(Y.Plugin.RecordsetIndexer);
	
	//You can now call methods to allow for custom hash tables on the myRecordset instance using the "indexer" namespace.
	
	myRecordset.indexer.createTable('a');

});

Using the RecordsetIndexer Plugin

• Creating a Hash Table
• Accessing Hash Tables
• Performing Standard Operations
• Collision Handling

Creating a Hash Table

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.

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});
	myRecordset.plug(Y.Plugin.RecordsetIndexer);
	
	//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

});

Accessing Tables

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).

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});
	myRecordset.plug(Y.Plugin.RecordsetIndexer);
	
	//create two hash tables
	var hashA = myRecordset.indexer.createTable('a'),
	myRecordset.indexer.createTable('c'),
	
	//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;
});

Performing Standard Operations

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".

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.

Collision Handling

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.

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.