#

# Example: Recordset Filter Plugin

The RecordsetFilter plugin provides the ability to filter records within a specific Recordset instance.

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

The filter plugin allows operations to filter a Recordset instance. All the methods generate new Recordsets that are subsets of the original Recordset.

### Using the Plugin

- Filter by key/value
- Using custom filter functions
- Other ways to filter

The RecordsetFilter plugin supports filtering a Recordset instance using a custom filter function, or key/value pairs.

    YUI().use("recordset-base", "recordset-filter", function(Y) {
        var state_census_data = [
            {ANSI: "01000", STATE: "ALABAMA", TOTAL_POP: 4708708, LAND_AREA: 50744, POP_PER_SQ_MILE: 87.6},
            {ANSI: "06000", STATE: "CALIFORNIA", TOTAL_POP: 36961664, LAND_AREA: 155959.34, POP_PER_SQ_MILE: 217.2},
            {ANSI: "10000", STATE: "DELAWARE", TOTAL_POP: 885122, LAND_AREA: 1953.56, POP_PER_SQ_MILE: 401}
        ],

    	//instantiate a new Recordset
    	recordset = new Y.Recordset({records: state_census_data});

    	//Plug it with the Filter plugin
    	recordset.plug(Y.Plugin.RecordsetFilter);

    	//call filter methods with the 'filter' namespace
    	var subset = recordset.filter.filter("STATE", "CALIFORNIA");
    });

### Filtering by Key/Value

The filter() method can take a key as its first argument, and a value as its second. Doing so will return a subset of the original Recordset, with records that match the specific key/value pair.

    //call filter methods with the 'filter' namespace
    var subset = recordset.filter.filter("STATE", "CALIFORNIA");

### Filtering by Custom Function

Additionally, a custom function can be passed in to the filter method. In this scenario, all records will be evaluated against this function, and if a truthy value is returned, it will be pushed onto the returning sub-Recordset.

    var myCustomFilterFunction = function(item) {
    	var letter = item.getValue('STATE').charAt(0);
    	if (letter === 'M' || letter === 'N' || letter === 'O' || letter === 'P') {
    		return true;
    	}
    	else {
    		return false;
    	}
    };

    //All records which have a STATE property starting with "M", "N", "O", or "P" will be pushed onto the new Recordset.
    var subset = recordset.filter.filter(myCustomFilterFunction);

### Other Ways to Filter

As Recordset augments `Y.Arraylist`, methods from the `array-extras` sub-module can be used. Currently, the `RecordsetFilter` plugin supports `reject()` and `grep()`. However, using other methods from the `array-extras` utility is straight-forward:

    //use the 'array-extras' submodule
    YUI().use("recordset-base", "recordset-filter", "array-extras", function(Y) {

        var state_census_data = [
            {ANSI: "01000", STATE: "ALABAMA", TOTAL_POP: 4708708, LAND_AREA: 50744, POP_PER_SQ_MILE: 87.6},
            {ANSI: "06000", STATE: "CALIFORNIA", TOTAL_POP: 36961664, LAND_AREA: 155959.34, POP_PER_SQ_MILE: 217.2},
            {ANSI: "10000", STATE: "DELAWARE", TOTAL_POP: 885122, LAND_AREA: 1953.56, POP_PER_SQ_MILE: 401}
    	],
    	//instantiate a new Recordset
    	recordset = new Y.Recordset({records: state_census_data});

    	//Define a custom function
    	customFindFunction = function() {
    		...
    	}

    	//Use the Array.find method found in the array-extras sub-module
    	var subset = new Y.Recordset({
    	       records: Y.Array.find(recordset.get('records'), customFindFunction)
    	});
    });