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