You just purchased UniFilter! If you have any questions that are beyond the scope of this help file please feel free to email via my user page contact form here
Thank you. flGravity
UniFilter jQuery Plugin is a #1 solution for filtering, sorting and searching through a set of items that can be your online shop, a photo gallery or simply some set of items.
Plugin allows you to add multiple filters, range sliders or search boxes at the same time. Also it's possible to enable only a specific feature and disable all others.
UniFilter plugin uses "data-" attributes assigned to list items to get search, sort and filter params. Also for every filter, search or sort configuration you can define a custom function to get params in a different way rather than from "data-" attributes. For instance, you can get a name of the item from some element within item's DOM and then use it to perform searching.
Finally you can place UniFilter at the top of the grid or in a sidebar - simpy create an empty container and configure UniFilter to use it for its controls.
Key Features
Below you will find instructions how to install and configure UniFilter plugin
Before installing UniFilter Plugin you need to make sure that your website links jQuery Library.
To install UniFilter first of all you should copy its files to the corresponding folders under your website (see below). Plugin files you will find under the template folders (like "template1/" folder) when you unzip a package downloaded from the codecanyon.net website
The next step is to add UniFilter JS/CSS files into the <head> section of your index.html file
<link rel="stylesheet" href="css/unifilter.css"> <script type="text/javascript" src="js/jquery.unifilter.min.js"></script>
Make sure that you added "jquery.unifilter.min.js" below a line that links jQuery Library!
Now, let's assume you already have a working grid with some items that looks like this
<ul id="shop" class="shop"> <li class="shop-item">…</li> … <li class="shop-item">...</li> </ul>
Next, you should add a container so that UniFilter knew were to place filters, range sliders, sort & search boxes. Let's add a DIV element with ID "filters" just before UL element
<div id="filters" class="unifilter"> <!-- UNIFILTER WILL BE HERE --> </div> <ul id="shop" class="shop"> <li class="shop-item">…</li> … <li class="shop-item">…</li> </ul>
When it's done you should get back to the <head> section of you index.html file and add init code that should look like this
$(document).ready(function(){
// filter options
var filter_options = {};
// search options
var search_options = {};
// sort options
var sort_options = {};
// range options
var range_options = {};
// general options
var options = {
order: "filters,search,sort,range",
filters: null,
search: null,
range: null,
sort: null
};
// init UniFilter plugin
$('#filters').unifilter("#shop", options);
});
$.unifilter() plugin accepts two arguments - the first one is a selector or jQuery object for the item list (like UL element), second argument is a plugin configuration.
In above configuration the "order" option specifies an order in which filters, range sliders, search & sorting boxes should appear in UniFilter container. You can also disable some of the features simply by removing them from the "order" list or when you set "null" for one of the "filters:", "search:", "range:" or "sort:" options directly.
Now let's take a look on all plugin options and see what they do. Then we will specifically look on how to configure filters, range sliders, search & sorting.
Below you will find all plugin options with default values and brief explanation what they do
// default plugin options
var default_options = {
selector: '', // selector for items in list, none by default
animationType: 'opacity', // animation type for items, e.g. 'none', 'opacity',
// 'scale', 'translate' or 'rotate'
animationTime: 500, // duration of animation, ms
order: "filters, search, sort, range", // order in which to display filters, search, range and sort features
bestMatch: false, // if set to true display items in order of their best match
// otherwise show only those items that match all filters together
bestMatchText: 'You may also like', // message to display below "best match" items
bestMatchEmpty: 'No items found', // message to display if no items match selected filters
autoScroll: false, // scroll automatically to filtered items
autoScrollDelay: 1000, // delay for auto scroll, ms
deepLinking: true, // enable deeplinking for filters
hideEmptyFilters: false, // hide filters with no items, when leading filter is active
filters: null, // object with filters configuration, defaut null
search: null, // object with search configuration, default null
sort: null, // object with sort configuration, default null
range: null // object with range configuration, default null
};
// default filter options
var filter_options = {
display: true, // display this filter or not
title: '', // title for filter, none by default
subtitle: '', // subtitle for filter, none by default
multiple: false, // allow multiple filters to be selected at the same time
tooltip: false, // show tooltip with amount of items for this filter
leading: false, // whether this filter is leading
getFilterData: null, // custom function to get filter tags for item ("this" keyword refers
// to item DOM, while filter name is passed as argument;
// functions should return array with tags e.g. ["tag1, tag2, tag3"])
sortFilterTags: null // custom function to sort filter tags (array with filter tags is passed
// as argument; function should return new array with tags)
};
// default search options
var search_options = {
display: true, // display this search box or not
title: '', // title for search box, none by default
subtitle: '', // subtitle for search box, none by default
placeholder: 'Type here..', // placeholder text
getSearchData: null // function to get search data for an item ("this" keyword refers
// to item DOM, while search name is passed as argument;
// should return array with search params e.g. ["search1, search2, search3"])
};
// default sort options
var sort_options = {
display: true, // display this sorting box or not
title: '', // title for search box, none by default
subtitle: '', // subtitle for search box, none by default
placeholder: 'Sort by', // text for placeholder when no option is selected
options: {
"_dummy": {
label: '', // display name for this option, otherwise take sort option name
order: 'DESC', // default sorting order for this option
getSortData: null // function to get sorting data for an item ("this" keyword refers
} // to item DOM, while sort name is passed as argument;
// function should return number or string for sort )
}
};
// default range options
var range_options = {
display: true, // display this range select or not
title: '', // title for range select, none by default
subtitle: '', // subtitle for range select, none by default
scale: '0-100', // set a from/to scale in a form of '0-100'
precision: 0, // scale precision
prefix: '', // prefix to put before the numbers, e.g. '$'
getRangeData: null // function to get range data for an item ("this" keyword refers
// to item DOM, while range name is passed as argument;
// function should return a number)
};
You may be curious about the "bastMatch" option. So, when it's set to true, UniFilter will count matches with active filters, ranges and search queries and then move items with two or more matches to the top of list, while items with fewer matches will appear underneath a separating line with the text from "bestMatchText" option
In subsections below we will look specifically on how to configure filters, range sliders, search and sort boxes.
So let's start!
First step in configuring filters is to add "data-{filter_name}" attributes to the list items. Let's assume we want to filter list items by color and size
So, add a "data-color" and "data-size" attributes to list items. They can contain one or few values separated by a comma
<ul id="shop" class="shop"> <li data-color="blue, green" data-size="S,M,L" class="shop-item">…</li> … <li data-color="brown" data-size="L,XL" class="shop-item">...</li> </ul>
Next we go back to UniFilter init code and add this
$(document).ready(function(){
// filter options
var filter_options = {
"color": {
title: 'Color',
subtitle: 'Select one of few colors',
multiple: false,
tooltip: true,
leading: true
},
"size": {
title: 'Size',
subtitle: 'Select a size',
multiple: true,
tooltip: true
}
};
// general options
var options = {
order: "filters"
filters: filter_options
};
// init UniFilter plugin
$('#filters').unifilter("#shop", options);
});
As soon as you reload your webpage, UniFilter will display two filters - one for colors with all color values from "data-" attributes and another with all sizes.
Please note that filter option name like "color:" should match attribute name - "data-color". If you want to add filter with a name "some_filter", then all the list items should have "data-some_filter" attribute added.
Now let's take a look specifically on options that you can set for a certain filter
var filter_options = {
display: true, // display this filter or not
title: '', // title for filter, none by default
subtitle: '', // subtitle for filter, none by default
multiple: true, // allow multiple filters to be selected at the same time
tooltip: false, // show tooltip with amount of items for this filter
leading: false, // whether this filter is leading
getFilterData: null, // custom function to get filter tags for item ("this" keyword refers
// to item DOM, while filter name is passed as argument;
// functions should return array with tags e.g. ["tag1, tag2, tag3"])
sortFilterTags: null // custom function to sort filter tags (array with filter tags is passed
// as argument; function should return new array with tags)
};
Everything should be clear here, except maybe the "leading" option. So, when you set it to true, this filter becomes required for items to be visible. In our example when we click on a "blue" filter all items that don't have blue color won't be visible regardless of what size we have chosen. In other words, filter with the "leading" option works like logical "AND" with all other filters, range sliders and search boxes.
Also if you want to use "hideEmptyFilters" option to dynamically hide filters with no items in current context, then primary filter should be set as leading. If you set more than one filter as "leading" the first one in configuration will work as primary and will turn on/off other filters.
As you can see every filter configuration may haves two callback functions set - "getFilterData" and "sortFilterTags". Use "getFilterData" function to get params (tags) for a filter in different way as via "data-" attributes. You can use it for example to get filter params from DOM of the list item itself. Keyword "this" in "getFilterData" function corresponds to the item DOM element and the function should return an array with params for a filter. Finally if you need to sort filter tags (retrieved either via "data-" attributes or via "getFilterData" function) you should use "sortFilterTags" function that accepts array with filter tags and should return it after re-arrangement.
Searching works very similar to filtering and configuration is almost the same except of some options. Let's take again our example, but now we'll add a search box where customers will be able to type a clothing name.
We start with adding a new "data-name" attribute to list items with clothing name. Again, you can specify multiple words separated by a comma
<ul id="shop" class="shop"> <li data-name="jacket" data-color="blue, green" class="shop-item">…</li> … <li data-name="jeans, pants" data-color="brown" class="shop-item">...</li> </ul>
To add a search by a "name" you should configure UniFilter like this
$(document).ready(function(){
// filter options
var filter_options = {
"color": {
title: 'Color',
subtitle: 'Select one of few colors',
multiple: false,
tooltip: true,
leading: true
},
"size": {
title: 'Size',
subtitle: 'Select a size',
multiple: true,
tooltip: true
}
};
// search options
var search_options = {
"name": {
title: "Search Clothes",
placeholder: "Type here.."
}
};
// general options
var options = {
order: "filters,search",
filters: filter_options,
search: search_options
};
// init UniFilter plugin
$('#filters').unifilter("#shop", options);
});
As you can see there is an option called "placeholder". It defines a text for search input before customer starts typing anything.
Some other options that you can use for search box configuration are listed below
var search_options = {
display: true, // display this search box or not
title: '', // title for search box, none by default
subtitle: '', // subtitle for search box, none by default
placeholder: 'Type here..', // placeholder text
getSearchData: null // function to get search data for an item ("this" keyword refers
// to item DOM, while search name is passed as argument;
// should return array with search params e.g. ["search1, search2, search3"])
};
As with filters use "getSearchData" function to get search params in different way as via "data-" attributes.
UniFilter allows multiple filters, range and search boxes to be added, but you can add only ONE sorting box. However this single sorting box can contain different options for sorting, e.g. price, name, size. Similar to filters and search boxes, every sorting box retrieves its params from the data- attributes of list items.
Let's assume we want to be able to sort our list by popularity from 1 to 10. So we add a "data-popularity" attribute to list items, see below
<ul id="shop" class="shop"> <li data-popularity="7" data-name="jacket" data-color="blue, green" class="shop-item">…</li> … <li data-popularity="2" data-name="jeans, pants" data-color="brown" class="shop-item">...</li> </ul>
Next we go back to UniFilter init code and add a sorting option
$(document).ready(function(){
// filter options
var filter_options = {
"color": {
title: 'Color',
subtitle: 'Select one of few colors',
multiple: false,
tooltip: true,
leading: true
},
"size": {
title: 'Size',
subtitle: 'Select a size',
multiple: true,
tooltip: true
}
};
// search options
var search_options = {
"name": {
title: "Search Clothes",
placeholder: "Type here.."
}
};
// sort options
var sort_options = {
title: 'Sorting',
subtitle: 'Please select an option to sort',
options: {
"popularity": {
label: 'Popularity',
order: 'DESC'
}
}
};
// general options
var options = {
order: "filters,search,sort",
filters: filter_options,
search: search_options,
sort: sort_options
};
// init UniFilter plugin
$('#filters').unifilter("#shop", options);
});
As you can see sorting box configuration is a bit different as we saw for filters and search boxes - all sort params you add to the options sub-property with the names corresponding to the "data-" attributes of list items.
As you can see we configured the "popularity" option with default DESC sorting order and a label "Popularity"
var sort_options = {
display: true, // display this sorting box or not
title: '', // title for search box, none by default
subtitle: '', // subtitle for search box, none by default
placeholder: 'Sort by', // text for placeholder when no option is selected
options: {
"_dummy": {
label: '', // display name for this option, otherwise take sort option name
order: 'DESC', // default sorting order for this option
getSortData: null // function to get sorting data for an item ("this" keyword refers
} // to item DOM, while sort name is passed as argument;
// function should return number or string for sort )
}
};
Also for every sorting option you can specify a custom function to get a sorting value in some other way as from the "data-" attribute.
The last feature of UniFilter is a range slider. You can add as many range sliders as you want and UniFilter will show items that match selected ranges. You can use it for example to filter items by a price or some other numeric value
So, we start with adding an attribute to the list items called "data-price" (you can also use getRangeData() function to get a price from some element within an item DOM)
<ul id="shop" class="shop"> <li data-price="10" data-popularity="7" data-name="jacket" data-color="blue, green" class="shop-item">…</li> … <li data-price="15" data-popularity="2" data-name="jeans, pants" data-color="brown" class="shop-item">...</li> </ul>
UniFilter init code with the range slider will look like this
$(document).ready(function(){
// filter options
var filter_options = {
"color": {
title: 'Color',
subtitle: 'Select one of few colors',
multiple: false,
tooltip: true,
leading: true
},
"size": {
title: 'Size',
subtitle: 'Select a size',
multiple: true,
tooltip: true
}
};
// search options
var search_options = {
"name": {
title: "Search Clothes",
placeholder: "Type here.."
}
};
// sort options
var sort_options = {
title: 'Sorting',
subtitle: 'Please select an option to sort',
options: {
"popularity": {
label: 'Popularity',
order: 'DESC'
}
}
};
// range options
var range_options = {
title: 'Price Range',
subtitle: 'Please select price range to filter items',
scale: '0 - 50',
prefix: '$',
precision: 0
};
// general options
var options = {
order: "filters,search,sort,range",
filters: filter_options,
search: search_options,
sort: sort_options,
range: range_options
};
// init UniFilter plugin
$('#filters').unifilter("#shop", options);
});
Here are all options that you can use to setup a range selection box
// default range options
var range_options = {
display: true, // display this range select or not
title: '', // title for range select, none by default
subtitle: '', // subtitle for range select, none by default
scale: '0-100', // set a from-to scale in a form of '0-100'
precision: 0, // scale decimal precision
prefix: '', // prefix to put before the numbers, e.g. $ (dollar sign)
getRangeData: null // function to get range data for an item ("this" keyword refers
// to item DOM, while range name is passed as argument;
// function should return a number)
};
With the "scale" option you can setup a min/max value of a range. Then with the "prefix" you can add some prefixes to the numbers. And finally with the "precision" option you can set number of digits after the decimal place.
UniFilter plugin adds some classes to the list items as well as generates events to help synchronize it with your code or 3rd-party plugins.
Thanks for reading!