6.5. Filterable

Allows for filtering of elements matching a given jQuery selector. The elements that do not pass the filter are hidden until the filter is updated and their visibility is reevaluated.

Each element that is to be filterable must define on itself the appropriate data attributes by which it can be filtered. If a data attribute is not provided, the element is ignored by the filter for that particular condition and is treated as if it passed the filter.

The options to be passed to the Filterable plugin are always an array of filter definition objects. If using the data-API, each of these objects has to be represented by a single :input element with the appropriate data-* attributes.

To allow users to view all filterable elements when using the data-API, simply place a button with type="reset" attribute within the filter <form>.

JavaScript Required

Script `filterable.js` must be included.

Usage

Data-API

The filter has to be a <form> with a data-filter-target attribute containing a string which, when evaluated as a jQuery selector, returns a jQuery object holding the DOM elements to be filtered.

Each of the :input elements of the form that are to be used for filtering have to define the data-toggle="filter" attribute. Further each one also has to possess the data-filter-attrib and data-filter-operator attributes (see the Filter Object section below).

To save the filter conditions to the browser session storage set the attribute data-filter-storage-id. This identifies the data in the context of the given host, domain and path combination. If the filter form changes the filter data in session storage that are not applicable any more are silently ignored.

The element that is to reset the filter on click has to have the data-toggle="reset-filter" attribute defined.

JavaScript

Filter Object
Name Type Default Description
filter-attrib string Defines the name of the `data-` attribute of the filterable objects to use for filtering.
filter-value string The filter value to be used in the condition. When using the data-api, this is automatically generated from the `:input` element value and does not not have to be set manually.
filter-operator enum Defines how to compare the values. If comparing strings or arrays of strings, we can use either `subset` or `intersect` operators. For comparing numeric values, the `=`, `<`, `>`, `<=` and `>=` are available.
Filter object `filter-value` Filterable element `data-*` attribute value Operator Description
[string] string intersect Checks if the filterable string attribute is a member of the filter object value array.
[string] [string] intersect Checks if the filterable array attribute has at least one common element with the filter object value array.
[string] [string] subset Checks if the filterable array attribute elements are all members of the filter object value array.
string [string] intersect Checks if the filterable array attribute contains the filter object value string.
number number = Checks if the filterable numeric attribute is equal to the filter object numeric value.
number number > Checks if the filterable numeric attribute is greater than the filter object numeric value.
number number < Checks if the filterable numeric attribute is lower than the filter object numeric value.
number number >= Checks if the filterable numeric attribute is greater than or equal to the filter object numeric value.
number number <= Checks if the filterable numeric attribute is lower than or equal to the filter object numeric value.
filter-strict - When `data-filter-strict` is present, both strings must be equal to produce a match. This differs from normal behavior where only part of the string can be used to get a match. Only applicable if `data-filter-operator` is set to intersect.
Methods
$().filter(filterObjects)

Filters the set of elements on which it is called according to the given array of filter objects.

$().resetFilter()

Displays all filterable elements.

Events
Event Type Description
resetStart.bui.filterable Fired as soon as the `reset` method is called.
resetEnd.bui.filterable Fired as soon as the `reset` method is finished executing.
filter.bui.filterable Fired when the `filter` method is called.
filtered.bui.filterable Fired when the `filter` method is finished executing.

Example

# User Place of Birth Cash Residence Countries Visited Favorite Meal Allergens
1 Brown, James Prague 10 Philadelphia China, Russia Hamburger, Pizza, Spagethi 1
2 Paisley, Brad Denver 15 Philadelphia China, USA Hamburger, Hotdog, Fries 2
3 Parker, Maceo Munich 8 Toronto USA, Russia, Denmark Fries, Meatloaf 3
4 Cimrman, Jára Liptákov 25 Vienna China, Russia, Germany Goulash 1, 2, 13
5 Smith, John Munich 17 Sydney Germany, Holland, Denmark Meatloaf, Hotdog 11
6 Scholizin, Vladimir Moscow 5 Philadelphia USA Pizza, Goulash 12
7 Wesley, Fred Denver 0 Toronto Germany, Russia, Denmark Pizza, Hotdog 13
<div class="row">
    <form class="form-filter offset-bottom" data-filter-target="#people tr" data-filter-storage-id="filterable-example">
        <div class="row">
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Place of Birth</label>
                    <select
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="birth-place"
                        data-filter-operator="intersect"
                    >
                        <option value="">All</option>
                        <option value="Denver">Denver</option>
                        <option value="Liptákov">Liptákov</option>
                        <option value="Moscow">Moscow</option>
                        <option value="Munich">Munich</option>
                        <option value="Prague">Prague</option>
                        <option value="Vienna">Vienna</option>
                    </select>
                </div>
            </div>
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Cash under</label>
                    <input
                        type="text"
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="cash"
                        data-filter-operator="<"
                    >
                </div>
            </div>
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Cash over</label>
                    <input
                        type="text"
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="cash"
                        data-filter-operator=">"
                    >
                </div>
            </div>
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Allergens</label>
                    <input
                        type="text"
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="allergens"
                        data-filter-operator="intersect"
                        data-filter-strict
                    >
                </div>
            </div>
        </div>
        <div class="row">
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Country visited</label>
                    <select
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="countries-visited"
                        data-filter-operator="intersect"
                        multiple
                    >
                        <option value="">Any</option>
                        <option value="China">China</option>
                        <option value="Denmark">Denmark</option>
                        <option value="Germany">Germany</option>
                        <option value="Holland">Holland</option>
                        <option value="Russia">Russia</option>
                        <option value="USA">USA</option>
                    </select>
                </div>
            </div>
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Residence</label>
                    <select
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="residence"
                        data-filter-operator="intersect"
                        multiple
                    >
                        <option value="Denver">Denver</option>
                        <option value="Philadelphia">Philadelphia</option>
                        <option value="Sydney">Sydney</option>
                        <option value="Toronto">Toronto</option>
                        <option value="Vienna">Vienna</option>
                    </select>
                </div>
            </div>
            <div class="col-sm-3">
                <div class="form-group">
                    <label>Favorite meal </label>
                    <select
                        class="form-control"
                        data-toggle="filter"
                        data-filter-attrib="favorite-meal"
                        data-filter-operator="subset"
                        multiple
                    >
                        <option value="Fries">Fries</option>
                        <option value="Goulash">Goulash</option>
                        <option value="Hamburger">Hamburger</option>
                        <option value="Hotdog">Hotdog</option>
                        <option value="Meatloaf">Meatloaf</option>
                        <option value="Pizza">Pizza</option>
                        <option value="Spagethi">Spagethi</option>
                    </select>
                </div>
            </div>
            <div class="col-sm-3">
                <div class="form-actions">
                    <button
                        type="reset"
                        class="btn btn-default"
                        data-toggle="filter-reset"
                    >
                        Reset Filter
                    </button>
                </div>
            </div>
        </div><!-- .row -->
    </form>
    <div class="table-responsive">
        <table class="table table-hover">
            <thead>
                <tr>
                    <th class="table-cell-id">#</th>
                    <th>User</th>
                    <th>Place of Birth</th>
                    <th>Cash</th>
                    <th>Residence</th>
                    <th>Countries Visited</th>
                    <th>Favorite Meal</th>
                    <th>Allergens</th>
                </tr>
            </thead>
            <tbody id="people">
                <tr
                    data-birth-place="Prague"
                    data-residence="Philadelphia"
                    data-cash="10"
                    data-countries-visited='["China", "Russia"]'
                    data-favorite-meal='["Hamburger", "Pizza", "Spagethi"]'
                    data-allergens='["1"]'
                >
                    <td class="table-cell-id">1</td>
                    <td><a href="#"><strong>Brown</strong>, James</a></td>
                    <td>Prague</td>
                    <td>10</td>
                    <td>Philadelphia</td>
                    <td>China, Russia</td>
                    <td>Hamburger, Pizza, Spagethi</td>
                    <td>1</td>
                </tr>
                <tr
                    data-birth-place="Denver"
                    data-residence="Philadelphia"
                    data-cash="15"
                    data-countries-visited='["China", "USA"]'
                    data-favorite-meal='["Hamburger", "Hotdog", "Fries"]'
                    data-allergens='["2"]'
                >
                    <td class="table-cell-id">2</td>
                    <td><a href="#"><strong>Paisley</strong>, Brad</a></td>
                    <td>Denver</td>
                    <td>15</td>
                    <td>Philadelphia</td>
                    <td>China, USA</td>
                    <td>Hamburger, Hotdog, Fries</td>
                    <td>2</td>
                </tr>
                <tr
                    data-birth-place="Munich"
                    data-residence="Toronto"
                    data-cash="8"
                    data-countries-visited='["USA", "Russia", "Denmark"]'
                    data-favorite-meal='["Fries", "Meatloaf"]'
                    data-allergens='["3"]'
                >
                    <td class="table-cell-id">3</td>
                    <td><a href="#"><strong>Parker</strong>, Maceo</a></td>
                    <td>Munich</td>
                    <td>8</td>
                    <td>Toronto</td>
                    <td>USA, Russia, Denmark</td>
                    <td>Fries, Meatloaf</td>
                    <td>3</td>
                </tr>
                <tr
                    data-birth-place="Liptákov"
                    data-residence="Vienna"
                    data-cash="25"
                    data-countries-visited='["China", "Russia", "Germany"]'
                    data-favorite-meal='["Goulash"]'
                    data-allergens='["1", "2", "13"]'
                >
                    <td class="table-cell-id">4</td>
                    <td><a href="#"><strong>Cimrman</strong>, Jára</a></td>
                    <td>Liptákov</td>
                    <td>25</td>
                    <td>Vienna</td>
                    <td>China, Russia, Germany</td>
                    <td>Goulash</td>
                    <td>1, 2, 13</td>
                </tr>
                <tr
                    data-birth-place="Munich"
                    data-residence="Sydney"
                    data-cash="17"
                    data-countries-visited='["Germany", "Holland", "Denmark"]'
                    data-favorite-meal='["Meatloaf", "Hotdog"]'
                    data-allergens='["11"]'
                >
                    <td class="table-cell-id">5</td>
                    <td><a href="#"><strong>Smith</strong>, John</a></td>
                    <td>Munich</td>
                    <td>17</td>
                    <td>Sydney</td>
                    <td>Germany, Holland, Denmark</td>
                    <td>Meatloaf, Hotdog</td>
                    <td>11</td>
                </tr>
                <tr
                    data-birth-place="Moscow"
                    data-residence="Philadelphia"
                    data-cash="5"
                    data-countries-visited='["USA"]'
                    data-favorite-meal='["Pizza", "Goulash"]'
                    data-allergens='["12"]'
                >
                    <td class="table-cell-id">6</td>
                    <td><a href="#"><strong>Scholizin</strong>, Vladimir</a></td>
                    <td>Moscow</td>
                    <td>5</td>
                    <td>Philadelphia</td>
                    <td>USA</td>
                    <td>Pizza, Goulash</td>
                    <td>12</td>
                </tr>
                <tr
                    data-birth-place="Denver"
                    data-residence="Toronto"
                    data-cash="0"
                    data-countries-visited='["Germany", "Russia", "Denamrk"]'
                    data-favorite-meal='["Pizza", "Goulash"]'
                    data-allergens='["13"]'
                >
                    <td class="table-cell-id">7</td>
                    <td><a href="#"><strong>Wesley</strong>, Fred</a></td>
                    <td>Denver</td>
                    <td>0</td>
                    <td>Toronto</td>
                    <td>Germany, Russia, Denmark</td>
                    <td>Pizza, Hotdog</td>
                    <td>13</td>
                </tr>
            </tbody>
        </table>
    </div>
</div><!-- .row -->