JavaScript

A5.ListBoxsetFilter Method

Syntax

A5.ListBox.setFilter(filter)

Arguments

filterbooleanstringobjectfunctionregexp

The filter to use on the list.

Description

Filter the list data.

Discussion

Filtering the list can be done by passing one of several types of filter.

If a function is passed in, the function will be called with the data for each row in the list. If the function returns true then that row will be visible. A return value of false will hide the row temporarily until the filter is removed. The scope of the function will be the list.

If a regular expression or string is passed in, then each column that is a string in each row of the list data will be tested against the string or regular expression. If the string or regular expression is found in the column then the row will be visible. If it is not found then the row will be temporarily hidden until the filter is removed.

If specific columns should be filtered for different values, then an object can be passed in. Each property of the passed in object will be tested against the data for the column in the row data with the matching name. The test can be done with a function, regular expression or string, all of which will behave similarly to the above, only the data they are tested with will only be the value of the specific column.

A value of false can be passed in to remove all filters.

Example

// To get a pointer to the A5.ListBox class see {dialog.object}.getControl
// assume lObj is a pointer to an instance of the A5.ListBox class
lObj.setFilter('ALFKI'); // filter the list for any instances of the string "ALFKI"
lObj.filterState = 'MA';
lObj.setFilter({ // specific filters on multiple columns
	FirstName: 'Fred', // first name must contain "Fred"
	State: function(state){
		if(state == this.filterState) return true; // check to see if the state for the given row is equal to the stored value - in this case "MA"
		return false;
	}
});
lObj.setFilter(/[0-9]/) // filter with a regular expression that checks all columns (that are strings) for numbers characters
lObj.setFilter(false) // remove filter

Example: Performing a Client-side Search in a List Control

The following example shows several ways to set the filter. The filter can be set using regular expressions (RegExp) or a JavaScript function. The filter definition can use either a RegExp or function for each field specified in the JSON object defining the filter.

var listObj = {dialog.object}.getControl('list1');
//search for specific record
listObj.setFilter(
    {
        Firstname: RegExp('John','i'), 
        Lastname: RegExp('Smith','i'), 
        City: RegExp('Boston','i'), 
        State: RegExp('MA','i')
    }
);

//search for Firstname is 'John' or 'Fred' or 'Henry'
listObj.setFilter(
    {
        Firstname: RegExp('John|Fred|Henry','i') 
    }
);

//search using a single function. data for the entire current row is passed into the function
listObj.setFilter(function(data){
     // data is the row data
    if (data.Color == 'red' || data.Color == 'green') { return true; } // yes, show this row
    else { return false; } // no, hide this row
});

//using Regular Expressions on some fields and functions on other.
//filter on the Name starts with an "E" or the Age is between 18 and 65 - note the value of "Age" gets passed into the function.
listObj.setFilter(
    {
        Name: RegExp('^E','i'), 
        Age: function(val){
        if(val < 18 || val > 65) return false;
        else return true;
        }
    }
);

//clear the filter
listObj.setFilter(false);
If you want to search all columns in a List Control on a UX Component, use the .filterListClientSide() method.
If the rows in the list are strings not objects, then a passed in function, regular expression or string will be tested against row string. Since there are no columns in the list, the object filtering cannot be done.

See Also