listFilter jQuery plugin

February 13, 2009 at 3:59pm.

This entry is about Programming

A project I am working on needed a way to filter a long list of staff members. We needed to be able to filter by several different criteria, and several different interfaces (text search, dropdown lists). And it needed to happen in-place—no page reloads. Thus my listFilter jQuery plugin was born.

listFilter allows you to automatically filter out items from a list on the fly, using any number of criteria and data items. You can look at the example to see how it works.

How to use

First you need to inlude jQuery and the plugin script:

<script src=”/scripts/jquery.min.js”></script> <script src=”/scripts/jquery.listfilter.js”></script>

You will need to things in you page: a list to filter and a form containing the controls you will use to set the filter criteria. These controls can be text inputs, textboxes, or select boxes. The list can be an actual list—<ul> or <ol>—or it can be any other element containing a group of similar elements (for instance a <table>, which contains <tr> elements). The trick here is that each filter criteria needs to match up with a sub-element of the list items. So if your list item looks like this: <li><h3 class=“name”>Name</h3> <p>Plumber</p></li>, you could have a criteria form that looks like this:

<form id=“criteria”> <label>Name:> <input type=“text” id=“name_filter” /> <label>Job:> <input type=“text” id=“job_filter” /> </form>

You will notice that the id of each filter matches the class of an item in the list, with “_filter” added to the end. That is how the script knows what to filter.

Finally, you need to initialize the filtering with this line of code (either in the head of you document, or in an external script):

$(document).ready(function() { $('#listToFilter').listFilter('#criteria'); });

There are three optional settings that you can pass to the listFilter function as a second parameter. listElement lets you specify the child element of #listToFilter that represents an individual item (default is “li”). transition specifies the effect used to show and hide the list items—can be “toggle”, “slide”, or “fade” (default is “toggle”). Finally, speed specifies the speed at which the transition will take place (default is 500). So if you wanted to filter the rows of a table by sliding unneeded rows up slowly, you would use:

$(document).ready(function() { $('#tableToFilter').listFilter('#criteria', {listElement: 'tr', transition: 'slide', speed: 2000}); });

Download the script

Leave a comment if you have any questions or improvements. This plugin is loosely based on liveSearch by John Nunemaker as revised by John Resig.

Comments:

Conrad on October 26, 2009 at 10:12am#1

Hey thanks for this script.

How well will it handle large amounts of weblog entries in an ee site for instance?

I’m thinking, listing archived news stories and using the search as a filter ?

EliVZ on October 26, 2009 at 10:59am#2

Conrad-
Since all the processing is done client-side, it will depend on the browser. I haven’t tried it will more than ~50 items, but since all of the processing is done on cached copies of the elements (rather than traversing the DOM repeatedly) it should be reasonably quick. If it starts to get bogged down, setting the speed to 0 will disable the graphical transitions, which will do a lot to speed things up (those transitions take quite a bit of processing power!).

Let me know how it goes!

Conrad on October 28, 2009 at 4:35am#3

Cheers mate I will let you know how it goes. There may be usability issues with paging when you have many entries but for small weblogs it should work

Vincent Roman on December 2, 2009 at 11:43am#4

Hey Eli -

Great little plugin you have here. Just wondering if it works with AJAXed content, i.e in instances where in JQuery you might use the LIVE function.

Thanks, Vincent -

Eli Van Zoeren on December 3, 2009 at 10:17pm#5

Vincent-

Currently, the script wouldn’t take into account the updated list, although it could easily be updated to do so by moving the line that sets the rows variable inside the filter function (this would entail a slight performance hit, but probably not significant).

You could also simply call the script again in the callback from your AJAX function, if the code duplication doesn’t bother you.

Richard Wiggins on November 7, 2011 at 11:50am#6

Hi Eli,

I know this is a little old now, but just found your plugin which is great for working on some prototype mocks-ups I’m working on.

Couple of questions:

Is there anyway I can control the results by using links instead of the form elements listed?

I’m also trying to show results of nested lists as well and this is partially working, but it doesn’t filter right down i.e. if I use the search filter it will find the results of the nested item, but shows the parent group… that probably makes no sense whatsoever!

Here’s the nested code I’m trying to use:
<li> <h4 class=“name type”>Article</h4> <ul> <li class=“name”>An Article Title in here</li> <li class=“name”>An Article Title in here</li> <li class=“name”>An Article Title in here</li> <li class=“name”>An Article Title in here</li> <li class=“name”>An Article Title in here</li> </ul> </li> <li> <h4 class=“name type”>AV</h4> <ul> <li class=“name”>An AV Title in here</li> <li class=“name”>Vimeo Video from somewhere</li> <li class=“name”>SoundCloud audio title</li> <li class=“name”>YouTube Video Title</li> <li class=“name”>Amazing video item</li> </ul> </li>

Searching for ‘vimeo’ shows:

AV
An AV Title in here
Vimeo Video from somewhere
SoundCloud audio title
YouTube Video Title
Amazing video item

When ideally it would just show:

AV
Vimeo Video from somewhere

Hope that makes some sense.

Cheers, Richard.

EliVZ on November 7, 2011 at 1:05pm#7

Richard,

Making it work with links rather than a form would take some work. One easy fix might be to use hidden radio controls and just style their labels to look like links.

For nested lists problem, grab the plugin code again (I changed one line to make this work….) and then pass in a listElement option that specifies how to find the items you want to filter. So, you might use listElement: “li li” for your example. This won’t hide the type titles, unfortunately, without some extra logic in the plugin.

Alternatively, you might look at something like Masonry for more filtering and sorting options. The code is on this page is just something I threw together quickly a few years ago, and is fairly limited in scope.

Richard Wiggins on November 7, 2011 at 5:43pm#8

Thanks Eli, think you’re right regarding the radio buttons - I could probably get something to work around that.

Great, I’ll try the plugin again later. Just got back after a 4 hour commute - damn trains!

Hadn’t seen that Masonry plugin, looks pretty good.

Many thanks again.

Richard Wiggins on November 7, 2011 at 6:26pm#9

Me again. I’ve tried the updated plugin but that doesn’t really work for me. Bit hard to explain but it’s still not showing the child list items on their own, but now it’s also not showing the parent list’s children i.e.

Filtering by ‘AV’ was showing the following which I did want:

AV
An AV Title in here
Vimeo Video from somewhere
SoundCloud audio title
YouTube Video Title
Amazing video item

It now just shows:

Any ideas? If not could you possibly let me have a link to your last version or let me know what line of code you altered…. I stupidly overwrote your last version of the JS and don’t have a backup!

Isotope looks good but most is overkill for what I need, and it doesn’t have your lovely search filter option either :(

EliVZ on November 8, 2011 at 11:58am#10

I just changed var rows = list.children(opts.listElement); to var rows = list.find(opts.listElement);. (And fixed a couple small bugs I noticed that shouldn’t affect anything.)

However, I realize now that using “li li” as the listElement probably won’t work. I think you need to use a class, something like “li.name:not(.type)”. Again, that’s just off the top of my head, so I don’t know for sure if it will work. Should get you closer, though.

Richard Wiggins on November 9, 2011 at 10:28am#11

Thanks for getting back to me Eli.

I’ve managed to get it working how it was before, but still can’t seem to get the additional child filtering working via the search.

I’m going to leave it for now, as this is just being used a mock-up and will no doubt be changed in the end by the developers.

Thanks again for all your help.

Eli Van Zoeren