Filterable Widget

Filterable Widget

The filterable widget allows you to filter the children of an element. The filtering is accomplished by applying the class ui-screen-hidden to those children for which a filter callback function provided via the widget's filterCallback option returns true.

Backwards compatibility

The filterable widget is a generalization of the listview widget's filter extension that was available in jQuery Mobile 1.3. It retains API compatibility with the listview filter. Its behavior is also made backwards compatible by the following deprecated features:

• If no source is provided for the filterable via a data-input attribute, it will generate a text input and place it before the element.
• It provides the filterPlaceholder option which sets the placeholder attribute on the generated text input.
• It provides the filterTheme option which sets the theme option on the generated text input.
• If a collapsibleset, selectmenu, controlgroup, or listview widget is instantiated on the element whose children are to be filtered, it synchronizes those widget options with the generated text input that the text input widget also provides (options such as "corners" or "mini").
• It provides special handling for listviews:
  • When filtering listview items, the default filter callback will not hide list items marked as dividers, however,
  • When filtering listview items, the widget enables the listview widget's hidedividers option, which causes the new listview hidedividers extension to automatically hide dividers for categories wherein all items are hidden.
  Together, these two behaviors reproduce the jQuery Mobile 1.3 behavior of the listview filter.

Setup

To render the children of an element filterable, perform the following steps:

1. Create an element that will serve as the source for the filterable. It can be any element that emits a change signal and has a value that can be accessed via the jQuery .val() plugin. This is usually a text input. The filterable widget reacts to the change signal by reading the value of the input after a short delay and iterating over all the children to determine whether they should be shown or hidden according to the filter callback provided.
2. Add the attribute data-filter="true" to the element whose children will be filtered.
3. Add the attribute data-input to the element whose children will be filtered. The value of the attribute is a string containing a jQuery selector that will return the element to be used as the source for the filterable.
4. Add the child elements that will be filtered. You may add or remove child elements at any time, however, when you add or remove child elements you should call the refresh method on the filterable widget, to ensure that the new children are shown or hidden in accordance with the latest input provided by the user.

   Child elements may have the data-filtertext attribute set. In that case, the default filter callback will hide a given child element only if the value of the data-filtertext attribute does not contain the string provided by the user. If the data-filtertext attribute is absent, the child will be hidden if its text content does not contain the string provided by the user.

<form>
  <input type="text" data-type="search" id="filterable-input">
</form>
<form data-role="controlgroup" data-filter="true" data-input="#filterable-input">
  <label for="pizza">
    Pizza
    <input type="checkbox" id="pizza">
  </label>
  <label for="goulash">
    Goulash
    <input type="checkbox" id="goulash">
  </label>
  <label for="falafel">
    Falafel
    <input type="checkbox" id="falafel">
  </label>
  <label for="spring-rolls">
    Spring Rolls
    <input type="checkbox" id="spring-rolls">
  </label>
</form>

"Reveal" mode

The normal initial state of a filterable widget is that all the children are shown. In contrast, a filterable in "reveal" mode initially hides all its children. Once the user starts filtering, however, the filterable widget will display only those children that contain the text entered by the user, whether the filterable widget is in "reveal" mode or not.

You can turn on "reveal" mode by adding the attribute data-filter-reveal="true" to the element whose children will be filtered.

The example below illustrates the behavior of a filterable widget in "reveal" mode:

<form>
  <input type="text" data-type="search" id="filterable-input">
</form>
<form data-role="controlgroup" data-filter-reveal="true" data-filter="true" data-input="#filterable-input">
  <label for="pizza">
    Pizza
    <input type="checkbox" id="pizza">
  </label>
  <label for="goulash">
    Goulash
    <input type="checkbox" id="goulash">
  </label>
  <label for="falafel">
    Falafel
    <input type="checkbox" id="falafel">
  </label>
  <label for="spring-rolls">
    Spring Rolls
    <input type="checkbox" id="spring-rolls">
  </label>
</form>

Custom filters

The filterable widget's filterCallback option allows you to set a custom callback. In the example below items are filtered by their ordinal, which can be specified using page printing conventions such as "1,2" or "4-9", or both ("1,2,4-9,12").

$.mobile.filterable.prototype.options.filterCallback = function( index, searchValue ) {
  var idx;
 
  if ( searchValue ) {
    searchValue = searchValue.split( "," );
    searchValue = $.map( searchValue, function( element ) {
      var ar = element.split( "-" );
        return ar.length === 1 ? parseInt( element ) :
          [ [ parseInt( ar[ 0 ] ), parseInt( ar[ 1 ] ) ] ];
    });
    for ( idx = 0 ; idx < searchValue.length ; idx++ ) {
      if ( ( $.type( searchValue[ idx ] ) === "number" &&
          index === searchValue[ idx ] ) ||
        ( $.type( searchValue[ idx ] ) === "array" &&
          index >= searchValue[ idx ][ 0 ] &&
          index <= searchValue[ idx ][ 1 ] ) ) {
        return false;
      }
    }
  }
 
  return !!searchValue;
};

The filterable widget runs the filter on its children upon instantiation to ensure that the initial list of displayed children satisfies the initial value of the input source. By setting the attribute data-enhanced="true", you instruct the filterable widget that no initial filtering is to be performed. This means that you must apply the class ui-screen-hidden to any children which must initially be hidden due to the initial value of the search input.

Note: If the element whose children are to be filtered is enhanced by another widget as well, such as for example a listview or a controlgroup then you are required to provide pre-rendered markup for the other widget as well, because the attribute data-enhanced="true" will influence the initialization behavior of the other widget as well.

In the example below, pre-rendered markup for a filterable is provided. The attribute data-filter-reveal="true" is explicitly specified, since the presence of the ui-screen-hidden class on all the children indicates that they are initially hidden. The controlgroup widget containing the children is also pre-rendered, because the data-enhanced="true" attribute applies to the controlgroup widget as much as it does to the filterable widget.

<form>
  <input id="pre-rendered-filterable" data-type="search">
</form>
<div
  class="ui-controlgroup ui-controlgroup-vertical ui-corner-all"
  data-role="controlgroup"
  data-filter="true"
  data-input="#pre-rendered-filterable"
  data-filter-reveal="true"
  data-enhanced="true">
  <div class="ui-controlgroup-controls">
    <a href="index.html" class="ui-screen-hidden" data-role="button">General</a>
    <a href="settings.html" class="ui-screen-hidden" data-role="button">Settings</a>
    <a href="advanced.html" class="ui-screen-hidden" data-role="button">Advanced</a>
    <a href="notifications.html" class="ui-screen-hidden" data-role="button">Notifications</a>
  </div>
</div>