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
With UniFilter jQuery Plugin you can easily add filtering, range selection, searching and sorting to your online shop or any other grid of items, like your portfolio or photo gallery. All of the plugin features can be used together or you can activate them separately. For instance, if you are looking for live search, then you can enable only this option while keep filtering and sorting disabled.
You can place UniFilter at the top of the grid or in a sidebar. All filters, search boxes and range selections will appear automatically as soon as you add specific "data-" attributes to the list items and configure plugin accordingly.
Starting with v2.0 you can use one of four CSS3 animation effects for switching list items. Also there is a range selection available so you can filter items any numeric value, like date or price
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). Those 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 to the <head> section of your index.html
<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" after a line that links jQuery Library itself!
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 selections, 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, second argument is a plugin configuration. The "order" option specifies an order in which filters, range selections, search & sorting boxes will appear in filters container. You can also disable some of them 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 look on all plugin options and see what they do, then we will specifically look on how to configure filters, range selections, searching & 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 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"]) }; // 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, ranges, search and sorting.
So let's begin!
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 listed and another for all sizes that you set for items.
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 attribute "data-some_filter" 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"]) };
Everything should be clear here, except maybe the "leading" option. So, when you set it to true, this filter becomes necessary for items to be visible. In our example when we click on a "blue" filter then all items that don't have blue color won't be visible regardless of what size we have chosen. In other words, filter with "leading" option works like logical "AND" with all other filters, ranges and search boxes.
Also there is "getFilterData" option. This option accepts a custom function to get values for a filter as alternative to the "data-" attribute and it should return array with values for a filter.
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 for 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"]) };
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 option gets its values 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 what we do, is 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. You specify "title" and "subtitle" directly under "sort_options" object, but all of the sort options you add to the options property.
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. This can be useful when you have a shop and every item has some element with the price. So instead of adding "data-" attributes with the price, you can write a function to get price from that element. That way when you decide to change a price for items, there will be no need to change it in data attributes also
The last feature of UniFilter is a range selection. You can add as many range selections 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
As you already have guessed, 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)
<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 range configuration 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" plugin 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!