Filtre

Questions ou commentaires?

Needs translation

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">. 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. Optional: Override the default search type to perform an AND or an OR search by passing a JSON array through the data-wb-filter attribute and setting the filterType parameter.

    By default the filter plugin will apply an exact pattern match when searching through content.

    <ul class="wb-filter" data-wb-filter='{ "filterType": "and" }'>
    	<li>Alberta</li>
    	...
    </ul>
  3. 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.
  4. 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.
filterType Sets the type of search operator that will be applied to the filter. By default the filter will search for an exact pattern match, however developers can set the filter to search using an OR or AND operator. data-wb-filter='{"filterType": "[Type of search]"}'
None (default):
Will use the default exact pattern match when searching for items
and:
Will use an AND operator between search terms. Only items that contain all search terms will be shown
or:
Will use an OR operator between search terms. All items that contain any of the supplied search terms will be shown
source jQuery selector that will hold the filter's UI. data-wb-filter='{"source": "[jQuery selector]"}'
None (default):
Will add the UI at the beginning of the element where the class wb-filter is defined.
String (jQuery selector)
Will add the UI at the beginning of the element defined.
uiTemplate Pointer to the element wrapping your UI template. For more information, see the uiTemplate's essential behaviour data-wb-filter='{"uiTemplate": "#idToMyTemplate"}' JQuery selector that represent the template element on the current page.

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 ) {
});

Essential component behaviour

uiTemplate

  • The template must include an <input type="search">.
  • The template can display the amount of visible items and total items. To do so, add an element with the class .wb-fltr-info. Within this element, the following elements can be added to display information:
    • <span data-nbitem></span> will display the amount of visible items.
    • <span data-total></span> will display the total amount of items.
  • uiTemplate option is not compatible with source option, since there is no need to define a source when the uiTemplate can exist anywhere on the page. If both options are defined, only uiTemplate option will be registered.

Code example

<div id="filterTemplate">
	<div class="form-group">
		<label for="customSearchUI">Search</label>
		<input type="search" class="form-control" placeholder="Type a province name..." id="customSearchUI">
	</div>
	<p class="wb-fltr-info"><span data-nbitem></span> / <span data-total></span> provinces</p>
</div>

Test Cases

ID Test Scenario Test Steps Test Data Expected Results Actual Results Pass/Fail
01 Check "exact" filtertype identifies correct matches when something is found
  1. Visit the working example page
  2. Scroll down to the "Applying additional search filters" section
  3. Find the Filter Plugin under the "Exact pattern match (default)" section
  4. Enter "Alberta" in the Filter text field
Search term: "Alberta"

Only the "Alberta" entry should be shown.

All other entries should be hidden.

The filter plugin text should read: "Showing 1 filtered from 13 total entries"

As expected Pass
02 Check "exact" filtertype returns no results when nothing is found
  1. Visit the working example page
  2. Scroll down to the "Applying additional search filters" section
  3. Find the Filter Plugin under the "Exact pattern match (default)" section
  4. Enter "No Way" in the Filter text field
Search term: "No Way"

No matched entries should be shown.

The filter plugin text should read: "Showing 0 filtered from 13 total entries"

As expected Pass
03 Check "and" filtertype identifies correct matches when something is found
  1. Visit the working example page
  2. Scroll down to the "Applying additional search filters" section
  3. Find the Filter Plugin under the "AND operator" section
  4. Enter "New Lab" in the Filter text field
Search term: "New Lab"

Only the "Newfoundland & Labrador" entry should be shown.

All other entries should be hidden.

The filter plugin text should read: "Showing 1 filtered from 13 total entries"

As expected Pass
04 Check "and" filtertype returns no results when nothing is found
  1. Visit the working example page
  2. Scroll down to the "Applying additional search filters" section
  3. Find the Filter Plugin under the "AND operator" section
  4. Enter "Ontario Yukon" in the Filter text field
Search term: "Ontario Yukon"

No matched entries should be shown.

The filter plugin text should read: "Showing 0 filtered from 13 total entries"

As expected Pass
05 Check "or" filtertype identifies correct matches when something is found
  1. Visit the working example page
  2. Scroll down to the "Applying additional search filters" section
  3. Find the Filter Plugin under the "OR operator" section
  4. Enter "Ontario Alberta" in the Filter text field
Search term: "Ontario Alberta"

Only the "Ontario" and the "Alberta" entries should be shown.

All other entries should be hidden.

The filter plugin text should read: "Showing 2 filtered from 13 total entries"

As expected Pass
06 Check "or" filtertype returns no results when nothing is found
  1. Visit the working example page
  2. Scroll down to the "Applying additional search filters" section
  3. Find the Filter Plugin under the "OR operator" section
  4. Enter "Joe Jane Blah" in the Filter text field
Search term: "Joe Jane Blah"

No matched entries should be shown.

The filter plugin text should read: "Showing 0 filtered from 13 total entries"

As expected Pass

Source code

Filter source code on GitHub

Date de modification :