Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
223 lines (162 sloc) 16 KB
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Filtrify</title>
<meta name="description" content="Filtrify">
<meta name="keywords" content="javascript, jquery, filtering, filter, plugin" />
<meta name="author" content="Luís Almeida">
<meta name="viewport" content="width=device-width">
<link rel="stylesheet" href="css/style.css">
<link rel="stylesheet" href="css/sunburst.css">
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="js/highlight.pack.js"></script>
<script src="js/script.js"></script>
</head>
<body>
<!--[if lt IE 7]><p class=chromeframe>Your browser is <em>ancient!</em> <a href="http://browsehappy.com/">Upgrade to a different browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">install Google Chrome Frame</a> to experience this site.</p><![endif]-->
<div id="header" role="banner">
<h1><a href="http://luis-almeida.github.com/filtrify/">filtrify</a></h1>
<h2>Beautiful advanced tag filtering with HTML5 and jQuery</h2>
<p>by the same author of <a href="http://luis-almeida.github.com/jPages/">jPages</a>, <i>Luís Almeida</i></p>
<a href="https://twitter.com/lmgalmeida" class="twitter-follow-button" data-show-count="false">Follow @lmgalmeida</a>
<a href="https://twitter.com/share" class="twitter-share-button" data-url="http://luis-almeida.github.com/filtrify/" data-text="Filtrify - Beautiful advanced tag filtering with HTML5 and jQuery" data-via="lmgalmeida" data-related="lmgalmeida">Tweet</a>
<iframe src="//www.facebook.com/plugins/like.php?href=http%3A%2F%2Fluis-almeida.github.com%2Ffiltrify%2F&amp;send=false&amp;layout=button_count&amp;width=90&amp;show_faces=false&amp;action=like&amp;colorscheme=light&amp;font=arial&amp;height=21" scrolling="no" frameborder="0" style="border:none; overflow:hidden; width:90px; height:21px;" allowTransparency="true"></iframe>
<!--<div class="g-plusone" data-size="medium" data-href="http://luis-almeida.github.com/filtrify/"></div>-->
</div>
<div id="main" role="main">
<div id="content">
<div id="browsers"><em>IE7 - [buggy}</em> <em>IE8+, Chrome, Firefox, Opera, Safari - (tested)</em></div>
<h2 id="what">What?</h2>
<p>Filtrify is an advanced tag filtering plugin, inspired by <a href="http://harvesthq.github.com/chosen/" target="_blank">Chosen</a> multiple select feature and Orman Clark’s <a href="http://webdesigntutsplus.s3.amazonaws.com/tuts/291_vertical_menu/demo/index.html" target="_blank">Vertical Navigation Menu</a>.</p>
<p>Advanced because you can search tags within tags and filter items by multiple tags from different categories and get a live feedback on the number of items containing related tags.</p>
<h2 id="how">How?</h2>
<p>Filtrify makes use of the new HTML5 "data" attribute to store the metadata.</p>
<p>All you have to do is include a "data" attribute for each item in your list with the respective tags (metadata). If you have more than one category of tags, include them in another "data" attribute. You can add as much categories of tags as you need.</p>
<p>Filtrify will then go through all the data attributes you included in your items and it will create a search menu with as many fields as the different number of categories (data-attributes) you provided. Each field label in the menu fires a "popup" filtering panel and there's where all the magic happens.</p>
<p>The plugin instanciation is very simple, you just have to pass a "containerID" and a "placeHolderID" which is the ID of the element where you want to place the menu.</p>
<h2 id="usage">Usage</h2>
<p>Add jQuery, filtrify.js and filtrify.css to the &lt;head&gt; section of your page (correct file locations first):</p>
<pre class="html"><code>&lt;script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"&gt;&lt;/script&gt;
&lt;script src="js/fitrify.js"&gt;&lt;/script&gt;
&lt;link rel="stylesheet" href="css/filtrify.css"&gt;
</code></pre>
<p>The HTML markup is really easy to understand and set up. You just have to be careful about these five things:</p>
<ul>
<li>Insert the tags separated by <strong>", "</strong> (It's important that you leave a space after the comma).</li>
<li>Equal tags must always have the exact same text (case sensitive!).</li>
<li>If a tag has ", " in its text, you have to insert "\" before and after the comma, e.g., imagine "foo, bar" is a tag, you'd have to insert it like this: "foo\,\ bar".</li>
<li>Always use the same sequence of categories in all your items in case that you have more than one category of tags.</li>
<li>Try not to repeat the same tags in a category.</li>
</ul>
<p>So, imagine that you have a list of singers/bands and each one of them have a list of "genre" tags. Your HTML would have to look like this:</p>
<pre class="html"><code>&lt;div id="placeHolder"&gt;&lt;/div&gt;
&lt;ul id="container"&gt;
&lt;li data-genre="pop, rock, british, classic rock"&gt; The Beatles &lt;/li&gt;
&lt;li data-genre="rock, british, blues, classic rock"&gt; The Rolling Stones &lt;/li&gt;
&lt;li data-genre="alternative, electronic, female vocalists"&gt; Björk &lt;/li&gt;
&lt;li data-genre="rock, alternative, grunge"&gt; Foo Fighters &lt;/li&gt;
&lt;li data-genre="rock, classic rock"&gt; Bruce Springsteen &lt;/li&gt;
...
&lt;/ul&gt;
</code></pre>
<p>Then you just have to instantiate the plugin when the document is ready and pass the "containerID" and "placeHolderID":</p>
<pre class="javascript"><code>$(function() {
$.filtrify("container", "placeHolder");
});
</code></pre>
<p>And that's it! Check out the demos below to see it in action.</p>
<h2 id="demos">Demos</h2>
<ul>
<li><a href="music.html">Single category</a></li>
<li><a href="movies.html">Multiple categories</a></li>
<li><a href="isotope.html">Isotope integration</a></li>
<li><a href="highlight.html">Highlight matched items with the callback function</a></li>
<li><a href="legend.html">Add a legend with the callback function</a></li>
<li><a href="query.html">Instantiate with a custom query</a></li>
<li><a href="trigger.html">Trigger a custom query</a></li>
<li><a href="reset.html">Reset all filters</a></li>
<li><a href="close.html">Close panel after adding a tag</a></li>
<li><a href="block.html">Block "data" attributes from being added as categories</a></li>
<li><a href="lazyload.html">Load images with Lazy Load</a></li>
<li><a href="jpages.html">Add pagination with jPages</a></li>
</ul>
<h2 id="style">Style</h2>
<p>Filtrify default looks was inspired by Orman Clark’s <a href="http://webdesigntutsplus.s3.amazonaws.com/tuts/291_vertical_menu/demo/index.html" target="_blank">Vertical Navigation Menu</a> - see <a href="http://webdesign.tutsplus.com/tutorials/site-elements/orman-clarks-vertical-navigation-menu-the-css3-version/">tutorial</a>.</p>
<p>The plugin CSS file might look a bit confusing and long at the begining but I'm sure you'll find it easy to costumize after inspecting the HTML for just a bit.</p>
<p>Filtrify relies heavily in the ":before" and ":after" pseudo-elements and in the "content" property. If you're not familiar with them, here is a great <a href="http://coding.smashingmagazine.com/2011/07/13/learning-to-use-the-before-and-after-pseudo-elements-in-css/">article</a> to get started. Don't forget that IE8 only supports the "content" property if a !DOCTYPE is specified. If you also want to fully support IE7 you can try <a href="http://code.google.com/p/ie7-js/">IE7.js</a> (not tested!).</p>
<p>For the icons, I used <a href="http://nodeca.github.com/fontomas/">fontomas</a> to extract only the icons being used from the <a href="http://www.justbenicestudio.com/studio/websymbols/">web symbols</a> and <a href="http://somerandomdude.com/work/iconic/">iconic</a> webfonts. Don't forget to include the font files and correct the url in the CSS file.</p>
<h2 id="documentation">Documentation</h2>
<h3>Instantiation:</h3>
<pre><code>$.filtrify( containerID, placeHolderID, options );</code></pre>
<h3>Arguements:</h3>
<dl>
<dt>containerID <i>string</i> <i class="required">required</i></dt>
<dd>The ID of the container of the items you want to apply the plugin to.</dd>
<dt>placeHolderID <i>string</i> <i class="required">required</i></dt>
<dd>The ID of the element where you want to place the generated menu.</dd>
<dt>options <i>object</i> <i class="opcional">optional</i></dt>
<dd>Plugin options. See below.</dd>
</dl>
<h3>Options [type] [default]:</h3>
<dl>
<dt>noresults <i>String</i><i class="default">"No results match"</i></dt>
<dd>In this parameter you can set the "No results" search text when you're searching for tags.</dd>
<dt>hide <i>Boolean</i><i class="default">true</i></dt>
<dd>By default filtrify hides all the items that don't match the filtering query. If you set hide to false, filtrify will no longer hide the mismatched ones. Because you can still have access to the matched and mismatched items in the callback function, you can then do whatever you want with the result of the query. See the <a href="highlight.html">highlight demo</a>.</dd>
<dt>close <i>Boolean</i><i class="default">false</i></dt>
<dd>If you want the filtering panel to close after adding a tag, set close to "true". See <a href="close.html">demo</a>.</dd>
<dt>query <i>Object</i><i class="default">no default</i></dt>
<dd>You can instantiate the plugin with a default filtering query. This parameter receives an object with the same sturcture as the trigger method (See below). See <a href="query.html">demo</a>.</dd>
<dt>block <i>Array</i><i class="default">empty array</i></dt>
<dd>Filtrify goes through all the "data" attributes in your items and assumes they are all categories of metadata. If you need to use a data attribute to store some information and you don't want the plugin to index it as a category, you can add that "data" attribute to the block list. Filtrify won't think it's a category anymore. See <a href="block.html">demo</a>.</dd>
<dt>callback <i>function</i><i class="default">function (query, match, mismatch) {}</i></dt>
<dd>In this parameter you can pass a function that will run everytime a tag is added or removed. This function receives three arguments: The filtering query (object) and two HTML collections: the matched items (match) and the mismatched ones (mismatch).</dd>
<dd>There are a lot of interesting things you can do using the callback function, like adding a <a href="legend.html">legend</a>, <a href="highlight.html">highlighting matched items</a>, or even adding <a href="jpages.html">pagination, animations and lazy loading of images</a> with jPages, Animate.css and lazyload.</dd>
</dl>
<h3>Methods:</h3>
<dl>
<dt>Create an instance</dt>
<dd><pre><code>var ft = $.filtrify("containerID", "placeHolderID");</code></pre></dd>
<dt>Reset</dt>
<dd><pre><code>ft.reset();</code></pre></dd>
<dt>Trigger</dt>
<dd><pre><code>var query = {
category1 : [tags],
category2 : [tags],
...
};
ft.trigger( query );</code></pre></dd>
</dl>
<p>See <a href="trigger.html">trigger</a> and <a href="reset">reset</a> demos to have a better understanding of their usage.</p>
<h2 id="download">Download</h2>
<p>Download the last version from the project page on <a href="https://github.com/luis-almeida/filtrify">GitHub</a>.</p>
<h2 id="contact">Contact</h2>
<p>I intend to add more features in the future and especially make Filtrify touch friendly and responsive, but it will all depend on the amount of feedback I have from people actually using it. So if you're using Filtrify let me know!</p>
<p>I'm new to twitter but you can get in touch with me <a style="color:#099;" href="https://twitter.com/#!/lmgalmeida">there</a>. You can also visit my <a style="color:#DCF7DD;" href="https://github.com/luis-almeida">github</a> or send me an <a style="color:#DD4B39;" href="mailto:lmg.almeida@gmail.com">email</a>.</p>
<h2>Donate</h2>
<p>I didn't have a donate button when I first published this plugin because it is not my intention to make money from it.</p>
<p>I released Filtrify under the MIT license, so it is free for personal <b>and</b> commercial use.</p>
<p>However, I've been receiving a lot of amazing feedback from awfully generous people who often want to buy me a beer in order to show their gratitude for my work.</p>
<p>Donations are also the best way to support the development of Filtrify, allowing me to take some time to add more features in the future.</p>
<p>So if you like the plugin, be so kind as to make a small donation. Donations are made thru Paypal, but you don't need a Paypal account to make a donation.</p>
<p style="margin-bottom: 30px;">Any ammount will be deeply appreciated!</p>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----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-----END PKCS7-----
">
<input type="image" src="http://www.powersellersunite.com/buttonfactory/x-click-but04.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>
</div>
</div>
<a id="fork" href="http://github.com/luis-almeida"><img src="https://a248.e.akamai.net/assets.github.com/img/e6bef7a091f5f3138b8cd40bc3e114258dd68ddf/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f7265645f6161303030302e706e67" alt="Fork me on GitHub"></a>
<script>
var _gaq=[['_setAccount','UA-30247115-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>