Filter

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 ORs 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.

Events

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

$( document ).on( "wb-ready.wb-filter", ".wb-filter", function( event ) {
});

$elm.on( "wb-ready.wb-filter", function( event ) {
});

$( 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

Source code

Filter source code on GitHub