## Introduction

Imagine that you are developing a page that has a huge list or table of data that is being generated by the server. Now imagine that you are an end-user that needs to scroll through all that data in order to find what is needed. This is where instaFilta can greatly improve that experience by filtering out unwanted items in real-time as the user types in a text field.
That's pretty much it.

Oh, and it has a whole bunch of options available for you to customize that experince to your liking.

This demo page is meant to give you a quick idea if instaFilta is the right plugin for your project. Have you already decided? Great! Then you might want to get into the nitty gritty details. You will find everything you need on the instaFilta GitHub page.

Technical documentation and download

## Table of contents

1. A simple example
2. Target ALL the things!
3. Character casing and custom target classes
4. Highlighting matching characters
5. Only match the beginning of a word
6. Using sections of lists
7. onFilterComplete returns matched hits
8. Categorize/tag items
9. Yes, checkboxes!!
10. All or nothing

## A simple example

The following shows an example of using instaFilta's default options. You simply apply the instaFilta function on a text field.

Try it out by entering some text in the input field above the target list. The plugin will bind to any elements having the CSS class instafilta-target and it will ignore character casing. As we will see in other examples, all of this can be customized through the plugin's options.

- Carbon
- Cobalt
- Copper
- Gallium
- Gold
- Hafnium
- Iridium
- Xenon

    $('#my-input-field').instaFilta();

## Target ALL the things!

The plugin will look for any text inside an element having the instafilta-target class. In this example, not only can you filter on these important people's names, you can also filter on the year they were born.

Name | Born
--- | ---
Albert Einstein | 1879
Marie Curie | 1867
Isaac Newton | 1643
Henry Cavendish | 1731
Edwin Hubble | 1889

    <tr class="instafilta-target">
        <td>Albert Einstein</td>
        <td>1879</td>
    </tr>

## Character casing and custom target classes

In this example, the filtering term must match the character casing of the target elements. The plugin will not match "mars" but it will match "Mars".

Also note that we can use a custom CSS class for our targets, if you need to adhere to naming conventions.

- Mercury
- Venus
- Tellus
- Mars
- Jupiter
- Saturn
- Uranus
- Neptune

    $('#my-input-field').instaFilta({
        targets: '.planet-name',
        caseSensitive: true
    });

## Highlighting matching characters

By setting the markMatches option to true, you can highlight the matching text within the matching items in the list. The matching characters will get wrapped in a span element that has the instafilta-match CSS class. You can change this class by setting the matchCssClass option.

- Superman
- Wonderwoman
- Batman
- Spiderman
- The Hulk
- The Green Lantern
- Elektra
- Ant Man

    $('#my-input-field').instaFilta({
        markMatches: true
    });

## Only match the beginning of a word

Easy! Just set the beginsWith option to true.

- Bald Bull
- Soda Popinski
- Don Flamenco
- Mike

    $('#my-input-field').instaFilta({
        beginsWith: true
    });

## Using sections of lists

Many times, a large list of data will be grouped in some way. A group will typically contain a heading and perhaps more stuff. This example of animals is grouped by class, which is the heading for each group.

When filtering such a list, you probably want to hide the entire section, including heading etc. Just set the instafilta-section CSS class on the containing section element. That's it! And, you can of course customize that class name using the sections option.

Mammals

- Bear
- Badger
- Moose
- Hedgehog
- Tiger
- Orangutan
- Wombat
- Blue Whale

Reptiles

- Snapping Turtle
- Nile Crocodile
- Tiger Snake
- Green Iguana
- Alligator
- Chameleon
- Gekko
- Black Mamba

Birds

- Ostrich
- Atlantic Puffin
- Flamingo
- Hummingbird
- Penguin
- Albatross
- Toucan
- Mandarin Duck

    <div class="instafilta-section">
        <h2>Birds</h2>
        <ul class="example-list">
            <li><span class="instafilta-target">Ostrich</span></li>
            <li><span class="instafilta-target">Atlantic Puffin</span></li>
            <li><span class="instafilta-target">Flamingo</span></li>
            <li><span class="instafilta-target">Hummingbird</span></li>
            <li><span class="instafilta-target">Penguin</span></li>
            <li><span class="instafilta-target">Albatross</span></li>
            <li><span class="instafilta-target">Toucan</span></li>
            <li><span class="instafilta-target">Mandarin Duck</span></li>
        </ul>
    </div>

## onFilterComplete returns matched hits

After the filtering process is done, you might want to report just how many hits were found and perhaps show some message if no hits were found. This example shows you how.

- Peter
- Lois
- Stewie
- Chris

    var $myMessage = $('#some-result-message');

    $('#my-input-field').instaFilta({
        onFilterComplete: function(matchedItems) {

            var message = (matchedItems.length > 0)
                ? "I found " + matchedItems.length + " matches!"
                : "I couldn't find a thing..";

            $myMessage.text(message);
        }
    });

## Categorize/tag items

This is a bit similar to using sections, but it has some important differences. You can tag individual target items with several categories. Do this by defining one or more (comma separated string or array) categories in a data-attribute associated with the categoryDataAttr option. You can then use the filterCategory method to perform filtering based on those categories.

In this example, a select box is used to filter out humans and machines. Note that "RoboCop" exists in both the machine category and the human category.

- R2-D2
- Terminator
- John Connor
- Andreas Larsson
- Johnny 5
- Gordon Freeman
- Wall-E
- RoboCop

### If the HTML looks like this..

    <span class="instafilta-target" data-instafilta-category="human">Gordon Freeman</span>
    <span class="instafilta-target" data-instafilta-category="machine">Wall-E</span>
    <span class="instafilta-target" data-instafilta-category="human,machine,both">RoboCop</span>

### ..then we can filter it by category like this

    var insta = $('#filtering').instaFilta();

    /* This will show "Gordon Freeman" and "RoboCop" */
    insta.filterCategory('human');

    /* This will show "Wall-E" and "RoboCop" */
    insta.filterCategory('machine');

    /* This will only show "RoboCop" */
    insta.filterCategory('both');

## Yes, checkboxes!!

Given that we can feed several categories to the filterCategories method, we can create an interface that scoops up the values of checked checkboxes and use them for this pupose. Have a go at this example!

Europe Asia Africa

- Sweden
- India
- Angola
- Germany
- Japan
- Chad
- Belgium
- China
- Ghana
- Finland
- Thailand
- Kenya
- Croatia
- Vietnam
- Madagascar
- Belarus

### The checkboxes look like this..

    <input type="checkbox" value="europe">

### ..and the JavaScript looks like this:

    var instaFilta = $('.continents').instaFilta();

    var $myCheckboxes = $('.continent-check');

    $myCheckboxes.on('change', function() {

        var checkedCategories = [];

        $myCheckboxes.each(function() {
            if ($(this).prop('checked')) {
                checkedCategories.push($(this).val());
            }
        });

        instaFilta.filterCategory(checkedCategories);
    });

## All or nothing

When applying multiple categories at once, instaFilta will match any matching categories. In some cases however, like this following example, you want to make sure that items only match if they belong to all categories.

Swims Walks Flies Trots

- Ladybug
- Porcupine
- Bullshark
- Crocodile
- Camel
- Iguana
- Unicorn
- Flying Fish

### Example markup

    <input type="checkbox" value="walks">
    <input type="checkbox" value="flies">

    <span class="instafilta-target" data-instafilta-category="walks,flies">Ladybug</span>

### Example JavaScript (notice the second parameter, which is set to true)

    var instaFilta = $('.animals').instaFilta();

    var $myCheckboxes = $('.ability-check');

    $myCheckboxes.on('change', function() {

        var checkedCategories = [];

        $myCheckboxes.each(function() {
            if ($(this).prop('checked')) {
                checkedCategories.push($(this).val());
            }
        });

        instaFilta.filterCategory(checkedCategories, true);
    });