Filter

Questions or comments?

Purpose

Filters through content and only show content that match a certain keyword.

Use when

Working example

English example

French example

How to implement

  1. Add a class="wb-filter" to an element or a grouped of elements to be filter.

    If set on a <section>, <article> or <div> element
    Otherwise specified, it will filter and search for content in <li> then hide the group, default sub <section>, if there is not more list item
    If set on a <table> with multiple <tbody>
    Otherwise specified, it will filter rows and search for content in <th> contained in <tbody> except the row containing <th& scope="rowgroup|row"gt;. It is assumed those row is used to identify the row group header as the default scope for a row is "row".
    If set on any other element, like <ul> or <table> with one or zero <tbody>
    Otherwise specified, it will filter and search on <li> or on <tr> in <tbody> for tables
  2. Test the feature to see if it is properly configured and show correctly the number of total entries and the same upon filtering. If the number match, you are done.
  3. In the scenario of those number don't match or you want to filter in a complex design, see the feature configuration below and make your own adjustment.

Use a Callback to filter items

( function() {

	window[ "wb-filter" ] = {

		/*
		 * Filter Callback, called after items are filtered
		 *
		 * @$field: jQuery object of the search input field
		 * @elm: jQuery object of the element where the filter is applied
		 * @settings: JSON object of the user setting set on plugin initialisation
		 */
		filterCallback: function( $field, $elm, settings ) {
			var $sections =	$elm.find( "section" ),
				sectionsLength = $sections.length,
				s, $section;

			for ( s = 0; s < sectionsLength; s += 1 ) {
				$section = $sections.eq( s );

				if ( $section.find( settings.selector + ":visible" ).length === 0 ) {
					$section.addClass( "wb-fltr-out" );
				}
			}
		}
	};
} )();

Configuration options

All configuration options of the plugin are controlled by the data-wb-filter attribute or window[ "wb-filter" ]. Multiple jQuery selection "," are not supported by this feature and may produce unexpected result.

Option Description How to configure Values
selector Sets the item selector that it will search in and hidden if not found. Provide a valid jQuery selector.
None (default for list, section, div, article):
li
None (default for table with one tbody):
tr
None (default for table with tbodies):
tr:not(:has(th[scope]))
jQuery selector:
Any valid jQuery selector relative to where the plugin is initialized or the section selector.
section Sets the selector for the grouping of items. When defined, the "selector" will be relatively to that group. When no filter callback is defined, it identify the group to hide if all sub-items are not visible. Provide a valid jQuery selector.
None (default for list):
Undefined
None (default for section, div, article):
>section
None (default for table):
>tbody
jQuery selector:
Any valid jQuery selector relative to where the plugin is initialized.
hdnparentuntil A selector used to hide the parent, when an items need to be filtered out, until it reaches the matched element by the selector excluding the matching selector. Provide a valid jQuery selector.
None:
Undefined
None (default for table with tbodies):
tbody
jQuery selector:
Any valid jQuery selector relative to the selected items when it need to be hidden.
filterCallback Sets the a callback function called after the filtering. See the above code sample. Provide a javascript function.
None (default):
Will use the default callback
function:
Will be call on each time a filter is applied.

Events

Document the public events that can be used by implementers or developers.

Event Trigger What it does
wb-init.wb-filter Triggered manually (e.g., $( ".wb-filter" ).trigger( "wb-init.wb-filter" );). Initializes the plugin the filter and create the user interface (UI). Note: the filter plugin will be initialized automatically unless the .wb-filter element is added after the page has already loaded.
wb-ready.wb-filter Triggered automatically after the filter plugin initializes. Used to identify when and where the filter plugin initializes (target of the event).
$( document ).on( "wb-ready.wb-filter", ".wb-filter", function( event ) {
});
$elm.on( "wb-ready.wb-filter", function( event ) {
});
wb-ready.wb Triggered automatically when WET has finished loading and executing. Used to identify when all WET plugins and polyfills have finished loading and executing.
$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

Filter source code on GitHub

Date modified: