JSquared auto filter list

One of the updated objects released with JSquared 1.0 beta 2 is the auto filter object. This is a powerful object for filtering lists and is proving useful in a variety of circumstances, not least the creation of auto complete drop down lists for instance for searching.

At present the object only handles static lists, but by the time JSquared 1.0 is in final release, it will support live lists and a host of further options. That is to say that you would be able to provide a JSquared ADIJ or JSquared AJAX object as the list of values and the auto filter object will use that object to retrieve the list of values each time it needs to perform a filter.

The object is designed to work with a text input field and to respond to key presses to perform a filter. Within this structure, it is quite configurable. Lets have a look into the object and how to use it.

To initiate the object, create an instance using the "new" keyword. The constructor of the object takes 3 parameters, the third of which is optional:

1. field - a reference to the DOM node which the auto filter object will respond to and work with
2. data - the list of items to filter as an Array
3. options - some options for how the object should perform

The options

• objectMember - the array of data to filter can be an array of objects. If it is, the auto filter object needs to know which member on each object in the array contains the filter data. This option defines that.
• minLength - the minimum number of characters to be entered into the text field before filtering starts. Defaults to 1.
• hoverCssClass - the css class to add to the node which is hovered over (or selected) by the user once the filtered list is displayed
• matchAnyCharacter - a boolean value which if true will match the characters entered into the text field against any character in the data list. If false (the default) it only matches from the start of the items in the data list

Events
In addition to these options, you can respond to various events. Pass in event handlers with the options as follows

• onItemBound - fired when a matching item in the data list is found and bound to the document
• onItemSelect - fired when the user selects an item from the filtered list
• onFilteredListDraw - fired after the filtered list of items is added to the DOM tree

The first 2 events defined above run in the scope of the DOM node representing the relevant filtered list item. They both will get passed a parameter containing the original data for that list item. If the original data list was an array of objects, the whole object will get passed.

The third event defined above runs in the scope of the list of items.

The HTML
When the user enters a value into the field which is to support the filtered list, a list of matching items is added to the DOM immediately after the field. Assuming the value in the field is "value", this list will by default appear as follows:

<ul class="autoCompleteList">

<li><strong>value</strong> 1</li>

<li><strong>value</strong> 2</li>

<li><strong>value</strong> 3</li>

</ul>

This HTML can be styled by CSS. The css class defined for the currently hovered over item (or "hover" by default) is added to the appropriate list item.

Selecting an Item
When the user selects an item either by clicking on the item in the displayed filtered list or by using the keyboard (up and down cursor keys to choose an item and enter to select it), the value of that item is written into the field.

That is pretty much all there is to it. Its quite simple really!