<div class="intro">
    <p>The RecordsetFilter plugin provides the ability to filter records within a specific Recordset instance.</p>
</div>

<div class="example yui3-skin-sam">
{{>recordset-filter-source}}
</div>

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

<h3>Using the Plugin</h3>

<ul class="topspace">
	<li><a href="#keyvalue">Filter by key/value</a></li>
	<li><a href="#customFunction">Using custom filter functions</a></li>
	<li><a href="#other">Other ways to filter</a></li>
</ul>

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

```
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");
});
```


<h3 id="keyvalue">Filtering by Key/Value</h3>

<p>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.</p>

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


<h3 id="customFunction">Filtering by Custom Function</h3>

<p>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.</p>

```
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);
```

<h3 id="other">Other Ways to Filter</h3>

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

```
//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)
	});
});
```

