# 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

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

## 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 | Visit the working example page Scroll down to the "Applying additional search filters" section Find the Filter Plugin under the "Exact pattern match (default)" section 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 | Visit the working example page Scroll down to the "Applying additional search filters" section Find the Filter Plugin under the "Exact pattern match (default)" section 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 | Visit the working example page Scroll down to the "Applying additional search filters" section Find the Filter Plugin under the "AND operator" section 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 | Visit the working example page Scroll down to the "Applying additional search filters" section Find the Filter Plugin under the "AND operator" section 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 | Visit the working example page Scroll down to the "Applying additional search filters" section Find the Filter Plugin under the "OR operator" section 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 | Visit the working example page Scroll down to the "Applying additional search filters" section Find the Filter Plugin under the "OR operator" section 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 :
  2018-05-23