Ajax Type-Ahead Builder
In this topic ..
This builder attaches to an HTML text input field, and provides what is generally known as "type ahead" functionality for that input.
The Builder accomplishes this by generating client JavaScript that monitors a user's keystrokes as they enter information into the text field. As the user inputs text, script code calls back over HTTP to the server. In response, a list of choices, based on what has been typed so far, is returned from the server.
The Builder displays the list of returned items as a select list underneath the original text field. As the list is continually updated, a user can either continue to type a complete text entry or opt to select a choice from the server-provided list.
How do I...
Provide list choices from XML data?
Create an XML-based file than contains the words you want to use as source material for type-ahead functionality.
Place this Builder in a model. In the "XML Element" input, specify the XML sub-element that contains of the data you want to use as the universe of possible choices.
If the universe contains many possible choices, enter in the Maximum Results filed a value represent the maximum number of results to be displayed in the select list.
Apply the Builder and run the model to test type-ahead functionality.
Filter choices returned from the server?
On each user keystroke, this Builder s runtime code evaluates the reference provided as the Values input. The Builder decides, based on what the user has typed so far, what choices to display.
There are two basic filtering types we can use: one which selects all the values that start with the user s currently-typed data, the other that returns all values that contain the currently-typed data somewhere in the value.
If the number of possible values is extremely large, you may not want to have the Builder search through the entire list in this fashion to find the matching possibilities. Replace this behavior with your own filtering logic by specifying "Show all values" for the "Filter Mode" input value.
Then write a method that calls the Builder-generated LJO s getCurrentUserData() method to get the data typed so far and decides based on this what choices to return, and use this method in the Values input
Specifying Inputs
This Builder takes the inputs described in the table below. For help on inputs common to many or all Builders such as those in the Properties input group, see "Using the Builder Call Editor"
Input Name Description Name Enter a name for this Builder call. The Designer displays this name in the Builder Call List. This name will be used as a prefix for generated helper linked Java object and init() method.
Page Location Use the Page Location input to specify the page or pages on which this Builder call will act. Here you will select the tag representing text box to which you want to add type-ahead functionality. Alternatively, we can type in the page location syntax directly.
See Locating Control Builders on Pages for detailed documentation about the Page Location input and page location syntax.
Lookup Table Used Specify a Lookup table to use the table's "Label" items as the choices presented to the user. When a Lookup table is specified here, the "Values" and "XML Element" inputs below are hidden because their functions are supplanted by the Lookup Table specified.
Values Indirect reference that evaluates to the full set of possible choices for the Builder to consider. This can be a ${MethodCall} reference if you want to fetch a different set of values based on what the user has typed so far; otherwise, the complete set of choices will be scanned for matching values to present to the user
This reference can evaluate to any of a large number of"collection" types: including XML and comma-separated String, as well as to Java array, Iterator and Collection instances.
XML Element This input is available when Value type is XML data. Use this input to instruct the Builder to look only at a specified XML sub-element. Filter Mode Use this input to specify values to display to the user. This input can restrict certain elements from the Values input reference are to be shown based on what the user has typed so far. You can choose:
- Show values starting with data - To display elements of the Values reference that start with the characters the user has typed so far into the text input.
- Show containing data anywhere To display elements of the Values reference if they contain characters the user has typed so far, regardless of position in the text string. (beginning, end or middle).
- Show all values - To disable filtering. All Values elements are considered matches. This choice is useful if you want to do your own filtering, generally used in conjunction with a ${MethodCall} reference for the Values input.
Maximum Results Specify an upper limit on the number of suggestions to be displayed to the user. This limit is imposed after the Values reference is evaluated and any filtering has been applied.
Objects this builder creates
This Builder creates the following artifacts in the WebApp:
Linked Java Objects
<buildername>
- Provides runtime support.. Includes the methodgetCurrentUserData()
that returns a String consisting of the characters typed so far. This method is useful when doing custom filtering, in conjunction with a Filter Mode of "Show all values" and a ${MethodCall} reference for Values. The method referenced by the Values input can get the current user-typed string and use it to pre-filter the possible suggestions.