Sift.js

Sift.js is a UI component for filters. It offers 4 types of filters:

Filter type	Description	Example
☑️ Multiple choice	List of checkboxes	Show me: Aston Martins and Porsches
🔘 Single choice	List of radio buttons	Show me either: Aston Martins or Porsches
📆 Date	Single month datepicker	Made: on 20th Aug 2016
📆 📆 Date range	Multi-month datepicker	Made: between 1st Jan 2015 - 25th Dec 2015

Some benefits:

• Clean API: Complexities hidden away.
• Blackbox: Only 2 callbacks regardless of filter type!
• Modular: Utilizes stand-alone components.
• Object-Orientated: Pragmatic example of OOP in JavaScript - no more Cat extends Animal 😺

Getting Started

• Demo
• Dependencies
• Supported Browsers
• To Use
• To Run

Configuration

• type
• displayName

List Configuration

• filters
• activeFilter

Calendar Configuration

• calendarOptions

Callbacks

• onFilterApplied
• onFilterCleared

Markup

• Generated HTML
• Conditional CSS Classes
  • filters-showing
  • with-active-filter
  • without-scroll
  • with-multi-calendar

Getting Started

Demo

A demo of the library in action can be found here.

Dependencies

DateRange.js has 3 dependencies:

1. jQuery Not for long 😆
2. DateJust.js
3. DateRange.js

Supported Browsers

• Chrome ✅
• Opera ✅
• Firefox ✅
• Safari known issues (inherited from DateJust.js)

To Use

• Include jQuery
• Include CSS and JavaScript from DateJust.js
• Include CSS and JavaScript from DateRange.js
• Include CSS and JavaScript for Sift.js after steps above ☝️

<!-- CSS -->
<link href="date-just.min.css" rel="stylesheet">
<link href="date-range.min.css" rel="stylesheet">
<link href="sift.min.css" rel="stylesheet">

<!-- JavaScript -->
<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="date-just.min.js"></script>
<script type="text/javascript" src="date-range.min.js"></script>
<script type="text/javascript" src="sift.min.js"></script>

Create an instance:

var instance = new Sift(element, { options });

element can be a selector or a DOM element.

To Run

$ git clone git@github.com:callum-hart/Sift.js.git
$ cd Sift.js
$ npm install
$ grunt watch

Configuration

type

TODO: change types to multiple, single, date, date_range

• Details Type of filter. Available options are: checkbox, radio, calendar, multi_calender.
• Required Yes
• Type <String>
• Usage type: "checkbox"

displayName

TODO: rename displayName to labelName. The term displayName is also used in List filters which is a bit confusing.

• Details Name of filter (shown to user).
• Required Yes
• Type <String>
• Usage displayName: "Department"

List Configuration

Additional configuration options when type is either "checkbox" or "radio"

filters

• Details Filter models to render.
• Type Array <Object>
• Required Yes
• Usage:

  filters: [
    {
      "value": 1,
      "displayName": "Name"
    },
    {
      "value": 2,
      "displayName": "Email"
    }
  ]
  
  /*
    value is what can be passed to server.
    displayName is what the user sees.
  */
  

activeFilter

• Details Select existing filter/s by value.

• Required No

• Type <String> or <Number> or Array <String> or Array <Number>

• Usage:

  Example data when value type is <String>:

  filters: [
    {
      "value": "asto",
      "displayName": "Aston Martin"
    },
    {
      "value": "lamb",
      "displayName": "Lamborghini"
    },
    {
      "value": "pors",
      "displayName": "Porsche"
    }
  ]
  

  To select a single filter:

  activeFilter: "asto"
  

  When list type is "checkbox" to select multiple filters:

  activeFilter: ["asto", "pors"]
  

  Example data when value type is <Number>:

  filters: [
    {
      "value": 1,
      "displayName": "Petrol"
    },
    {
      "value": 2,
      "displayName": "Diesel"
    },
    {
      "value": 3,
      "displayName": "Electric"
    }
  ]
  

  To select a single filter:

  activeFilter: 3
  

  When list type is "checkbox" to select multiple filters:

  activeFilter: [1, 2]
  

Calendar Configuration

Additional configuration options when type is either "calendar" or "multi_calendar"

calendarOptions

• Details Configuration options for calendar.

• Required No

• Type <Object>

• Usage:

  When type is "calendar" calendarOptions supports all of the configuration options DateJust.js has:

  calendarOptions: {
    existingDate: new Date(2015, 2, 25)
  }
  

  When type is "multi_calendar" calendarOptions supports all of the configuration options DateRange.js has:

  calendarOptions: {
    minDate: new Date(2015, 0, 1),
    maxDate: new Date(2015, 11, 31),
    existingDateRange: [new Date(2015, 10, 5), new Date(2015, 11, 22)]
  }
  

Callbacks

onFilterApplied

onFilterApplied: (...args) {}

• Details When a filter is applied.

• Arguments:

  When type is "checkbox" or "radio" ...args is: (activeFilter).

  When type is "calendar" ...args can be: (singleDate) or (startDate, endDate).

  When type is "multi_calendar" ...args is: (startDate, endDate).

  In cases where ...args has multiple arguments the callback is only called when both arguments exist.

onFilterCleared

onFilterCleared: () {}

• Details When a filter is cleared.

Markup

The HTML generated by Sift depends on option type.

When type is "checkbox" HTML is:

<div class="sift-container">
  <a href="" class="sift-link">
    <span class="sift-filter-name">{{displayName}}</span>
    <span class="sift-active-filter-text">{{activeFilter}}</span>
  </a>
  <div class="sift-dropdown">
    <a href="" class="sift-clear">Clear filter</a>
    <div class="sift-dropdown-inner">
      <label class="sift-label">
        <input type="checkbox" name="{{displayName}}" value="{{filters[].value}}">
        <span>{{filters[].displayName}}</span>
      </label>
    </div>
  </div>
</div>

When type is "radio" HTML is:

<div class="sift-container">
  <a href="" class="sift-link">
    <span class="sift-filter-name">{{displayName}}</span>
    <span class="sift-active-filter-text">{{activeFilter}}</span>
  </a>
  <div class="sift-dropdown">
    <a href="" class="sift-clear">Clear filter</a>
    <div class="sift-dropdown-inner">
      <label class="sift-label">
        <input type="radio" name="{{displayName}}" value="{{filters[].value}}">
        <span>{{filters[].displayName}}</span>
      </label>
    </div>
  </div>
</div>

When type is "calendar" HTML is:

<div class="sift-container without-scroll">
  <a href="" class="sift-link">
    <span class="sift-filter-name">{{displayName}}</span>
    <span class="sift-active-filter-text">{{activeFilter}}</span>
  </a>
  <div class="sift-dropdown">
    <a href="" class="sift-clear">Clear filter</a>
    <div class="sift-dropdown-inner">
      <div class="sift-calendar-wrap dj-container">
        {{DateJust.js rendered here}}
      </div>
    </div>
  </div>
</div>

When type is "multi_calendar" HTML is:

<div class="sift-container without-scroll with-multi-calendar">
  <a href="" class="sift-link">
    <span class="sift-filter-name">{{displayName}}</span>
    <span class="sift-active-filter-text">{{activeFilter}}</span>
  </a>
  <div class="sift-dropdown">
    <a href="" class="sift-clear">Clear filter</a>
    <div class="sift-dropdown-inner">
      <div class="sift-calendar-wrap dr-container">
        {{DateRange.js rendered here}}
      </div>
    </div>
  </div>
</div>

Conditional CSS Classes

Classes that are applied when a certain condition is true.

filters-showing

.filters-showing

• Condition Applied when filter dropdown is visible.
• Element .sift-container

with-active-filter

.with-active-filter

• Condition Applied when a filter is selected/exists.
• Element .sift-container

without-scroll

.without-scroll

• Condition Applied when option type is "calendar" or "multi_calendar".
• Element .sift-container

with-multi-calendar

.with-multi-calendar

• Condition Applied when option type is "multi_calendar".
• Element .sift-container