listObj.searchList Method

Syntax

listObj.searchList([options]);

Arguments

optionsJSON object

An optional JSON format string that indicates where the search should be performed (client-side or server-side). In the case of server-side search, you can set additional optional properties (listed below).

searchMode Character: Defaults to 'serverSide'. Can be set to 'clientSide', 'serverSide' or 'auto'. The 'auto' option performs a server-side search if the List is not 'dirty' (i.e. does not have any unsynchronized edits). Otherwise, it performs a client-side search.
maxRowsnumber: Default is value set in Search Part of List Builder. In the case of a server-side search, indicates the maximum number of rows that the search is allowed to return. This property overrides the property that is set in the List Builder on the Search Part pane.
maxPayloadnumber: Default is value set in Search Part of List Builder. In the case of a server-side search, indicates the maximum payload that the search is allowed to return. This property overrides the property that is set in the List Builder on the Search Part pane.
xbasicAfterFilterComputestring: Default is no function. Defines the name of an Xbasic function that will be called after the filter has been computed, but before the SQL has been executed. See "Server-side After Search Expression Computed Event" below for more information.

Description

Submits the Search Part to search the List. You can specify if the search should be performed client-side, server-side or 'auto'.

Discussion

The searchList() method reads the search criteria from the Search Part for a List control and then performs either a client-side or server-side search. Additional options can be specified to defined the search behavior, including the search mode and the amount of data to return (rows, payload size).

var listObj = {dialog.object}.getControl("LIST1");

if (listObj) {
    listObj.searchList({searchMode : 'auto', maxRows: 30});
}

The List control's beforeSearch client-side event fires before the search is performed. This event exposes the searchWhere property that tells you where the search will be performed.

An optional Xbasic function can also be specified. This Xbasic function will be called prior to submitting the search on the server. The Xbasic function is not used for client-side searches.

Server-side After Search Expression Computed Event

The xbasicAfterFilterCompute argument can be used to override the computed search filter for the List control. The argument specifies an Xbasic function to call after the filter for the List has been computed but before any records are retrieved from the List's data source.

The Xbasic function specified must take e as a parameter. The e object contains the following properties:

e.tmpl - A pointer to the UX Component definition.
e.searchDefinition - An object with properties defining the filter expression computed by Alpha Anywhere from the submitted data.

The e.searchDefinition is a property array with the following properties:

e.searchDefinition Property: Description
parameters: The values for the arguments used in the filter expression. Syntax is a CR-LF delimited string with syntax for each line as: searchValue|||field_type|argument_name
filter: The SQL Where clause to be added to the base SQL query for the List.
order: The SQL order clause.
having: The SQL having clause.
distanceFromLocation: Used in geography searches.

The Xbasic function can modify any of the properties for the e.searchDefinition object to customize the search filter. For example, the code below overwrites the search parameters and filter to only search for records with a Country of 'UK':

function customizeListSearch as v (e as p)
    dim parameters as c = "%UK%|||C|search_country_country1"
    dim filter as c = "(Country LIKE :SEARCH_Country_Country1)"

    e.searchDefinition.parameters = parameters
    e.searchDefinition.filter = filter

end function

To call the Xbasic function as part of the List search process, the xbasicAfterFilterCompute option is used. The xbasicAfterFilterCompute option defines an Xbasic function that should be called to process the search filter before querying the Lists data source. For example:

var listObj = {dialog.object}.getControl('LIST1');

if (listObj) {
    listObj.searchList({xbasicAfterFilterCompute:"customizeListSearch"});
}

Limitations

List Control with Search Part