Filtreur.js

Declarative user interface library for filtering elements on a web page.

  1. Define the controls, the filters, and the data with HTML data attributes.
  2. Set the visual outcome with CSS.
  3. Include filtreur.js and get a live filtering user interface.

Examples

<!-- HTML -->
<!--
    For each button:
    "data-filter-in" tells where to filter
    "data-filter" tells what to filter
    "data-filter-keycode" defines a keyboard shortcut (optional)
-->
<button data-filter-in="items" data-filter="all" class="selected_filter">All</button>
<button data-filter-in="items" data-filter="tech" data-filter-keycode="49">Technology</button>
<button data-filter-in="items" data-filter="phil" data-filter-keycode="50">Philosophy</button>

<!-- The collection of elements to filter -->
<ul data-collection="items">
    <!-- Elements to filter have a data-filter attribute -->
    <li data-filter="phil">Link</li>
    <li data-filter="phil tech">Link</li>
    <li data-filter="tech">Link</li>
    <li data-filter="tech">Link</li>
    <li data-filter="phil">Link</li>
</ul>

<!-- Include filtreur.js -->
<script type="text/javascript" src="filtreur.js"></script>
/* CSS */
.selected_filter{
    /* styling for the selected filter button */
    color: #fff;
    background: #f65858;
}
.filtered_out{
    /* styling for elements that do not match the filter */
    display: none;
}

Example with select

<!-- HTML -->
<select>
    <option data-filter-in="items" data-filter="all">All</option>
    <option data-filter-in="items" data-filter="science">Science</option>
    <option data-filter-in="items" data-filter="education">Education</option>
</select>

<ul data-collection="items">
    <li data-filter="science">Link</li>
    <li data-filter="education">Link</li>
    <li data-filter="science">Link</li>
    <li data-filter="science">Link</li>
    <li data-filter="education">Link</li>
</ul>

<script type="text/javascript" src="filtreur.js"></script>
/* CSS */
.filtered_out{
    display: none;
}

Usage

Include the JavaScript file in HTML:

<script type="text/javascript" src="filtreur.js"></script>

Filtreur.js starts automatically. The remainder of the setup is done with HTML and CSS.

Controls

A control is what the user selects to filter elements. A control can be any HTML element, but it is recommended to use a semantically relevant element such as button or select. Example:

<button data-filter-in="items" data-filter="1" data-filter-keycode="49">1</button>

Collections

A collection contains the elements to filter. A collection can be any HTML container. Example:

<ul data-collection="items">
    <li data-filter="2">2</li>
    <li data-filter="1">1</li>
    <li data-filter="1 2">1 and 2</li>
</ul>    

CSS

Filtreur shows the result of the filtering by applying CSS classes:

.selected_filter{
    /* styling for the selected filters, applied to all corresponding controls */
}
.filtered_out{
    /* styling for filtered out elements */
}
.filtered_in{
    /* styling for filtered in elements */
}

Options

Filtreur does not require to write JavaScript code. However, some settings, API customization, and methods can be accessed with JavaScript.

Settings

Default settings can be modified inside filtreur.js or by making dedicated JavaScript calls:

//////////////////////////////////////////////////////////////////
//
// Default settings
//
//////////////////////////////////////////////////////////////////

// Default data-filter value to cancel filtering
filtreur.all = 'all';

// CSS class applied to elements which do not match a filter
filtreur.filtered_out = 'filtered_out';

// CSS class applied to elements which match a filter
filtreur.filtered_in = 'filtered_in';

// CSS class applied to all controls with the selected filter
filtreur.selected_filter = 'selected_filter';

// Calling the same filter twice in a row cancels filtering.
// Default is false. Set to true to enable
filtreur.toggle = false;

// Hitting Escape cancels filtering on the last filtered collection.
// Default is true. Set to false to disable
filtreur.escape = true;

API

The name of the dedicated data attributes can be customized by changing the values of the following variables inside filtreur.js:

//////////////////////////////////////////////////////////////////
//
// HTML API
//
//////////////////////////////////////////////////////////////////

// HTML5 conventions require data attributes to begin with "data-"
var data_attribute_filter = 'data-filter';
var data_attribute_filter_in = 'data-filter-in';
var data_attribute_collection = 'data-collection';
var data_attribute_keycode = 'data-filter-keycode';

Methods

Filtreur provides the following JavaScript methods:

// Filtering
// Takes a collection and a filter
filtreur.filter({
    collection: 'items',
    filter: '1'
});

// Unfiltering
// Filtering with filter: "all" is equivalent to unfiltering.
// The value "all" can be changed in settings
filtreur.filter({
    collection: 'items',
    filter: 'all'
});

// Execute a function after filtering
filtreur.callback_start = myFunction();

// Execute a function after unfiltering
filtreur.callback_end = myFunction();

// Tell the current selected filter
filtreur.current_filter;

// Tell the last filtered collection
filtreur.collection;

// Stop Filtreur from running
filtreur.stop();

// Start Filtreur. This method is automatically called by filtreur.js
filtreur.start();

Why Filtreur?

I have many web pages where the content is organized by tags, such as the Homepage, the Reading list, and the Blog. I wrote Filtreur to get a reusable component that could filter content on any web page.

I had the following requirements:

Compatibility

Supported browsers

Known issues

License

Filtreur.js is published under the GNU General Public License.