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

""