#

# Example: Recordset Indexer Plugin

The RecordsetIndexer plugin provides the ability to define custom hash tables to a Recordset instance.

State | Population | Land Area
--- | --- | ---

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.