When you have a list of items which share a lot of keys such as these:
var items = [
{
"firstname": "Mary",
"lastname": "Smith",
"imageURL": "http://flickholdr.iwerk.org/150/100/Mouse/0",
"description": "Sed Ea Amet. Stet Voluptua. Nonumy Magna Takimata ",
"category": "Mouse",
"language": ["Smalltalk", "XSLT"],
"continent": "Africa"
},
{
"firstname": "Patricia",
"lastname": "Johnson",
"imageURL": "http://flickholdr.iwerk.org/150/100/Lion/1",
"description": "Ut Takimata Sit Aliquyam Labore Aliquyam Sit Sit Lorem Amet. Ipsum Rebum. ",
"category": "Lion",
"continent": "North America"
},
...
]
You would like the user view these items, sort them by a certain key, and filter them by another. Maybe the user wants to see the Lions from North America and sort them by their firstname. This library gives you the means to do that and provides you with a way to generate the output just as you want it to be. First check out the demo, then read the documentation.
This library depends on the existence of jquery and underscore.
Two functions are exported into the jQuery namespace
facetelize is used to initialize the faceted search with the given settings.
facetUpdate can be used if you want to change the state of the faceted search from the outside.
items : An array of items which will be filtered and sorted in the process.
facets : An object for which the keys correspond to keys from the items and the values are the headline for this facet. The items will be filtered based on what value they have for these keys.
orderByOptions : Just like the facets, except that these key-value pairs are used for sorting only. When the key RANDOM is included, the results can be randomized.
facetSelector : This is the selector which is used to find the DOM-node where the facets are displayed.
resultSelector : This is the selector which is used to find the DOM-node where the results are displayed.
resultTemplate : A string that is used by the underscore templating system to render each item from the items array. The following attributes are added to each item which can be used in the template as well: batchItemNr, batchItemCount and totalItemCount.
state : This object stores the current filters, sort option, currentResult and other things. You can provide a orderBy string or an filters object to preset those.
enablePagination : Boolean to enable the pagination / "load more" functionality, defaults to true.
paginationCount : If pagination is enabled, set the number of items to display in a batch, defaults to 50.
facetSortOption : Use this to change the order of facet items. Takes an object in which the keys correspond to facet names and the values to an array of facet values which can be arranged in the order you would like them to appear. This example will sort the continents in a different order, elements which are not included in the array will be appended in alphabetical order:
facetSortOption : {'continent': ["North America", "South America"]}
There are some more templates, please have a look at the source of the facetedsearch.js to see all available template options.
You can bind to some Events to be notified when some actions have happened. This uses the jquery event system. They are:
facetuicreated : You can bind to this function on the settings.facetSelector DOM node to be notified when the UI has been created.
facetedsearchresultupdate : You can bind to this function on the settings.resultSelector DOM node to be notified when the results have been updated.
facetedsearchfacetclick : This event is fired when a facet is clicked and it is fired on the settings.facetSelector node. It receives the id of the facet as an argument.
facetedsearchorderby : This event is fired when a sortby item is clicked and it is fired on the settings.facetSelector node. It receives the id of the orderby as an argument.
$(settings.resultSelector).bind("facetedsearchresultupdate", function(){
// do something, maybe
});
Here you can see a typical setup which includes a DOM-node to display the facets in and one where to display the results in.
<div id=facets></div>
<div id=results></div>
<script src="dependencies/jquery-1.6.2.js"></script>
<script src="dependencies/underscore-1.1.6.js"></script>
<script src="facetedsearch.js"></script>
<script>
var example_items = [
{
"firstname": "Mary",
"lastname": "Smith",
"imageURL": "http://flickholdr.iwerk.org/150/100/Mouse/0",
"description": "Sed Ea Amet. Stet Voluptua. Nonumy Magna Takimata ",
"category": "Mouse",
"language": "XSLT",
"continent": "Africa"
},
{
"firstname": "Patricia",
"lastname": "Johnson",
"imageURL": "http://flickholdr.iwerk.org/150/100/Lion/1",
"description": "Ut Takimata Sit Aliquyam Labore Aliquyam Sit Sit Lorem Amet. Ipsum Rebum. ",
"category": "Lion",
"language": "Lisp",
"continent": "North America"
}];
var item_template =
'<div class="item">' +
'<img src="<%= obj.imageURL %>">' +
'<h4><%= obj.lastname %>, <%= obj.firstname %></h4>' +
'<p class="tags">' +
'<% if (obj.category) { %><%= obj.category %><% } %>' +
'<% if (obj.continent) { %>, <%= obj.continent %><% } %>' +
'<% if (obj.language) { %>, <%= obj.language %><% } %>' +
'</p>' +
'<p class="desc"><%= obj.description %></p>' +
'</div>';
var settings = {
items : example_items,
facets : {
'category' : 'What Category',
'continent' : 'Which Continent',
'language' : 'Programming Language'
},
resultSelector : '#results',
facetSelector : '#facets',
resultTemplate : item_template,
orderByOptions : {'firstname': 'First name', 'lastname': 'Last name', 'category': 'Category', 'RANDOM': 'Random'}
}
$(function(){
$.facetelize(settings);
});
</script>