- Skip to main content
- Skip to "About this site"

# Filter

Questions or comments?

## Purpose

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

## Use when

- Filter an exhaustive list
- Filter items structured uniformly in several sub-sections
- Filter a datatable or a row grouped datatable.

## 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:
  2017-07-21