A SearchField control enables a user to trigger a search according to keywords. Optionally, it is possible to provide a list containing suggestions which help the user to find easier what he or she is looking for.
The simplest form of a SearchField control is a TextField with a search icon as shown in the following example. When the user clicks the search icon,
or presses the Enter key, a search
event is fired based on the user's input.
The SearchField control can also be used to implement a live search or a filter functionality like in the following example. The suggest
event
of the control is used to immediately update the list of European countries.
Note: Please note that the value of the SearchField is different from the value that
is set as event-parameter. The value of the SearchField that is returned by the
getValue-method of the SearchField returns the value that was last set on the field after
the user pressed enter or changed the focus away from the SearchField. The value-parameter
of the suggest-event contains the string that is currently shown on screen. Always use the
event-value (oEvent.getParameter("value")
) instead of the control-value
(oSearch.getValue()
) when calculating suggestions.
See also: The
liveChange- and change-event
of the underlying TextField control for more information about the value difference.
The next example uses the same data (European countries) as in the example before. A suggestion list is opened when the user types more than
two characters (for this, a configurable parameter is available via property startSuggestion
). The list expander can optionally be shown or hidden (property showListExpander
).
The SearchField control also allows to attach a SearchProvider which takes over
the suggestion handling. This class is the abstract parent for concrete SearchProvider implementations. Currently the OpenSearchProvider is
the only concrete sub class. The suggestUrl
property of the OpenSearchProvider allows to specify a URL which is called to request the suggestions. The returned data
must be like specified in the Open Search Protocol where the JSON
and the XML response format are supported (see property suggestType
).
Note: Keep potential cross domain issues in mind when you specify a suggestion URL (e.g. use a proxy servlet).
The following example shows the connection to the suggestion functionality of the Demo Kit search.