Filtering Component - FooTable

# Filtering

## Display just the rows you want to see.

The filtering component allows you to quickly and easily display just the rows you want to see by providing a simple search input.

#### Note

See the Getting started - Examples section for examples of this component.

# Options

The below lists all the options for the filtering component, these are available in addition to the core options.

### General options

#### enabled boolean

Whether or not the component is enabled.

`false`

By default this component is disabled, no UI or features of this component will be available.

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table data-filtering="true">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"enabled": true
    		}
    	});
    });

#### filters array

An array of filters to apply to the tables rows.

A filter is a simple object containing a `name`, a `query` and an array of `columns`. The name is used purely as an identifier so duplicate filters are not applied. The query is the string that is used when determining whether a row should be included in the results or not. The columns specify which cell values from a row are used when applying the query. The columns values can be supplied as either an index (zero based) or as the `name` of the column.

`[]`

The below shows what one of the filter objects would look like.

    var filter = {
    	"name": string,
    	"query": string,
    	"columns": array
    };

To supply filters through data attributes you must follow valid JSON syntax including quoted property names.

    <table data-filter-filters='[{"name":"my-filter","query":"The value","columns":["id"]}]'>
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"filters": [{
    				"name": "my-filter",
    				"query": "The value",
    				"columns": ["id"]
    			}]
    		}
    	});
    });

#### Notes

- The `name` is used to avoid applying duplicate filters and when removing existing ones.
- The `query` is the value used to actually filter the rows with.
- The `columns` array is used to specify which columns the query applies to, the array values can be either the `name` or the zero based index of the column.

#### connectors boolean

Whether or not to replace phrase connectors (+.-_) with spaces before filtering the rows.

`true`

By default the plugin will replace phrase connectors (+.-_) with spaces before filtering the rows.

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-connectors="true">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"connectors": true
    		}
    	});
    });

#### delay number

The number of milliseconds before a search input filter is applied after it changes.

`1200`

By default the plugin waits 1.2 seconds (1200 milliseconds) before auto applying a new search filter, setting this option to any value equal to or less than zero will disable this feature.

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-delay="-1">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"delay": -1
    		}
    	});
    });

#### ignoreCase boolean

Whether or not to ignore case when filtering.

`true`

By default the plugin will ignore case as it provides a more natural feel to querying.

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-ignore-case="false">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"ignoreCase": false
    		}
    	});
    });

#### min number

The minimum number of characters in the search input before auto applying the filter.

`3`

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-min="4">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"min": 4
    		}
    	});
    });

#### placeholder string

The placeholder text displayed within the search input.

`"Search"`

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-placeholder="Suche">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"placeholder": "Suche"
    		}
    	});
    });

#### position string

The position of the search input within the filter row.

`"right"`

The other supported values for this option are `"left"` and `"center"`

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-position="center">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"position": "center"
    		}
    	});
    });

#### space string

Specifies how to treat whitespace in a filter query.

When evaluating a filter query this option specifies how whitespace in a string is treated. By default all whitespace is treated as an `AND` operator meaning that a row must contain all parts of the query, the parts are created by splitting the query on whitespace. When changed to `OR` a row must contain only a single part of the query to be included in the results.

`"AND"`

The only other supported value is `"OR"` for this option.

To supply this option through data attributes you must specify the attribute on the `table` element.

    <table class="table" data-filter-space="OR">
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"filtering": {
    			"space": "OR"
    		}
    	});
    });

### Column options

#### filterValue function

The function used to retrieve the filter value for a cell.

To improve the performance of the component all cells provide a string value to be used during filtering operations. Using a string value avoids having to perform any type conversions in an already expensive operation, this function is called whenever a cells filter value needs to be set.

`null`

By default the column will use its `type`s filterValue function.

`string`

To supply the function through data attributes it must be defined as a named JavaScript function with the name supplied as the attribute value.

    function filterValue(valueOrElement){
    	if (F.is.element(valueOrElement) || F.is.jq(valueOrElement)) return $(valueOrElement).data('filterValue') || $(valueOrElement).text();
    	if (F.is.hash(valueOrElement) && F.is.hash(valueOrElement.options)){
    		if (F.is.string(valueOrElement.options.filterValue)) return valueOrElement.options.filterValue;
    		if (F.is.defined(valueOrElement.value)) valueOrElement = valueOrElement.value;
    	}
    	if (F.is.defined(valueOrElement) && valueOrElement != null) return valueOrElement+'';
    	return '';
    }

    <table>
    	<thead>
    		<tr>
    			<th data-filter-value="filterValue">...</th>
    			...
    		</tr>
    	</thead>
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"columns": [{
    			"filterValue": function(valueOrElement){
    				if (F.is.jq(valueOrElement)) return valueOrElement.data('filterValue') || valueOrElement.text();
    				if (F.is.hash(valueOrElement) && F.is.hash(valueOrElement.options)){
    					if (F.is.string(valueOrElement.options.filterValue)) return valueOrElement.options.filterValue;
    					if (F.is.defined(valueOrElement.value)) valueOrElement = valueOrElement.value;
    				}
    				if (F.is.defined(valueOrElement) && valueOrElement != null) return valueOrElement+'';
    				return '';
    			}
    		},{
    			...
    		}]
    	});
    });

#### Note

The first argument (`valueOrElement`) is either the jQuery wrapper around the `td` element to parse or a value that needs to be parsed into a string.

#### filterable boolean

Whether or not the column is included in a rows value when filtering.

`true`

All columns can be searched by default, this would only need to be changed if a columns contents can not be represented as a string.

To supply this option through data attributes you must specify the attribute on the cell element.

    <table>
    	<thead>
    		<tr>
    			<th data-filterable="false">...</th>
    			...
    		</tr>
    	</thead>
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"columns": [{
    			"filterable": false
    		},{
    			...
    		}]
    	});
    });

### Cell options

#### filterValue string

The value used by the component to perform filtering operations.

`""`

To supply this option through data attributes you must specify the attribute on the `td` element.

    <table>
    	<tr>
    		<td data-filter-value="My Filter Value">...</td>
    		...
    	</tr>
    	...
    </table>

The below shows how to supply the value directly through the options.

    jQuery(function($){
    	$('.table').footable({
    		"rows": [{
    			"id": {
    				"options": {
    					"filterValue": "My Filter Value"
    				},
    				"value": ...
    			}
    		},{
    			...
    		}]
    	});
    });

#### Note

If no filter value is supplied for a cell the result of the default `toString` method executed on it's value will be used.

# Queries

By default the filtering component treats all whitespace as an `AND` operator, this behavior can be changed using the `space` option. The below example is probably the way most queries would be created which is why how whitespace is treated is very important. The difference between the results returned when using the `AND` and `OR` operators are very different. One would generally make the query more specific while the other would expand it to include more results.

`john smith`

The above query would match all rows containing both `john` and `smith`.

While the `space` option changes how whitespace is treated there are also the following basic operators that allow you to build up more advanced queries.

### AND

Make a query more specific by separating additional parts with a capitalized `AND` string.

`john AND smith`

The above query would match all rows containing both `john` and `smith`.

### OR

Expand a query by separating additional parts with a capitalized `OR` string.

`john OR smith`

The above query would match all rows containing `john` or `smith`.

### Negate

Exclude a value from the results by prefixing it with a minus `-` sign.

`john -smith`

The above query would match all rows containing the word `john` but would exclude any containing `smith`.

### Phrases

Match an exact word or phrase by wrapping it in quotes `"`.

`"brown fox"`

The above query would match all rows containing the exact phrase `brown fox`.

### Empty

Match empty values by using double quotes `""`.

`""`