instaFilta
instaFilta does in-page filtering and has absolutely nothing to do with Instagram.
Imagine that you have a web page displaying a huge list of data. It might be hard for the user to scan through all that data to find the thing he/she is interested in. instaFilta is a jQuery plugin that uses the input of a text field to perform in-page filtering, hiding non-matching items as the user types. Optionally, it can also filter out complete sections (groups of items) if there are no matching items in that section. If you don't use sections, you don't need to do anything special, it will work fine without specifying so.
Live demo
http://chromawoods.com/instafilta/demo/
General usage
Call instaFilta on the text field that should be observed, passing any of the options in an object. In the below example, we have specified that we only want to match items that begin with whatever the user types in the text field.
$('#username-filtering').instaFilta({ targets: '.username', beginsWith: true });Options
| Option | Type | Descriptions | Default value |
|---|---|---|---|
| scope | jQuery selector string | Selector of an element in which the input field and the targets are enclosed. Use this if you want to use multiple filter sections on your page | null |
| targets | jQuery selector string | Classname of an individual item. | '.instafilta-target' |
| sections | jQuery selector string | Classname of the sections holding the items. | '.instafilta-section' |
| categoryDataAttr | string | Name of data attributes in which to look for categories. (read more below) | 'instafilta-category' |
| matchCssClass | string | Classname of the spans indicating matching text. | 'instafilta-match' |
| itemsHideEffect | string | What jQuery effect to use for hiding items (slideUp etc.). | 'hide' |
| itemsHideDuration | integer | Duration (in ms) of item hide effect. | 0 |
| itemsShowEffect | string | What jQuery effect to use for showing items (slideDown etc.). | 'show' |
| itemsShowDuration | integer | Duration (in ms) of item show effect. | 0 |
| sectionsHideEffect | string | What jQuery effect to use for hiding sections (slideUp etc.). | 'hide' |
| sectionsHideDuration | integer | Duration (in ms) of section hide effect. | 0 |
| sectionsShowEffect | string | What jQuery effect to use for showing sections (slideDown etc.). | 'show' |
| sectionsShowDuration | integer | Duration (in ms) of section show effect. | 0 |
| onFilterComplete | function | Callback which is fired when the filtering process is complete. Recieves matchedItems, which is jQuery containing all matched items. | null |
| markMatches | boolean | If true, matching text will get wrapped by a span having the class name of whatever the matchCssClass option is set to. | false |
| hideEmptySections | boolean | If using sections, this option decides whether to hide sections which did not have any matching items in them. | true |
| beginsWith | boolean | We can choose to match the beginning of an item's text, or anywhere within. | false |
| caseSensitive | boolean | Whether to ignore character casing. | false |
| typeDelay | integer | The filtering process takes place on the keyUp event. If you have a large list of items to process, you might want to set a higher value (in milliseconds) to prevent the filtering to be able to occur so frequently. So in other words, it would kind of "wait" a bit while the user types. | 0 |
| useSynonyms | boolean | When set to true, this option will also match user input against a synonym list. | true |
| synonyms | object array | List of objects that contain synonyms. See section below. | Common accents, see below. |
Methods
filterTerm
Can be used to programmatically apply a filter. For normal simple usage, you will probably not be needing this.
Returns
Matched elements (jQuery)
Parameters
| Parameters | Description | Type | Default value |
|---|---|---|---|
| term | What search string to filter on. | string | undefined (will show all targets) |
filterCategory
Can be used to filter on one or more categories. See demo page for live examples.
Returns
Matched elements (jQuery)
Parameters
| Parameters | Description | Type | Default value |
|---|---|---|---|
| categories | One or more categories to use. | string, comma separated string or array of strings | undefined (will show all targets) |
| requireAll | If true, ALL categories must match each item, rather than any. | boolean | false |
Highlighting matching text
When filtering out list items, it might be valuable to highlight exactly what part of the text was matched. We can do this using the markMatches option. If set to true, the match will get wrapped by a span, having the matchCssClass option CSS class (which defaults to instafilta-match). Use this class to style the match within the item text.
Note: If you use this feature, you might encounter incorrect highlighting if you are using synonyms that are more than one character.
Synonyms
You can use synonyms to allow several characters or even words to match one single user input. This is helpful for accent letters but it can also be used for whole words, like aliases. Synonyms are used by default and the synonym list contains the following:
[ { src: 'à,á,å,ä,â,ã', dst: 'a' }, { src: 'À,Á,Å,Ä,Â,Ã', dst: 'A' }, { src: 'è,é,ë,ê', dst: 'e' }, { src: 'È,É,Ë,Ê', dst: 'E' }, { src: 'ì,í,ï,î', dst: 'i' }, { src: 'Ì,Í,Ï,Î', dst: 'I' }, { src: 'ò,ó,ö,ô,õ', dst: 'o' }, { src: 'Ò,Ó,Ö,Ô,Õ', dst: 'O' }, { src: 'ù,ú,ü,û', dst: 'u' }, { src: 'Ù,Ú,Ü,Û', dst: 'U' }, { src: 'ç', dst: 'c' }, { src: 'Ç', dst: 'C' }, { src: 'æ', dst: 'ae' } ] src contains a list of characters or words that should match dst, other than the input itself of course. As an example, if the user has typed Therese, it will match both Therese and Thérèse.
Categories
By appending a data-attribute named according to setting categoryDataAttr, it is possible to "label" or "tag" items. Use the filterCategory method to apply the category filter. You would typically use this together with some form element like a select or checkbox. Target items can belong to multiple categories, just separate them with a comma. The category parameter passed to filterCategory can also contain several comma separated categories.
<li class="instafilta-target" data-instafilta-category="human">John Connor</li> <li class="instafilta-target" data-instafilta-category="machine">Terminator</li> <li class="instafilta-target" data-instafilta-category="human,machine,both">RoboCop</li>var insta = $('#some-input').instaFilta(); /* This will show "John Connor" and "RoboCop" */ insta.filterCategory('human'); /* This will show "Terminator" and "RoboCop" */ insta.filterCategory('machine'); /* This will show only "RoboCop" */ insta.filterCategory('both');Multiple Filter Usage
If you have want to use instaFilta on more than one text input, you must supply instaFilta with a scope element selector. The scope element must enclose both the text input field and the targets it should filter.
$('#username-filtering').instaFilta({ scope: '.container-div', targets: '.username', beginsWith: true });
