AutoSuggest |
|
|
|
|
|
AutoSuggest |
|
|
|
|
AutoSuggest |
|
|
|
|
|
AutoSuggest |
|
|
|
|
|
|
||
An auto-suggest field is a text field (and its associated control widget) where the rest of contents of the field are suggested to the user in a popup below the field, and the user selects the correct information. The suggestions are obtained from a dynamic data service (DDS). A common use case for auto-suggest is entering a household address with suggestions coming from a geodata DDS.
Here is how the field looks and behaves:
For the autoSuggest widget to work, the widget configuration has to correspond to the Groovy scripts of the service in the "Service Definitions" page of Avoka Transaction Manager. In other words, unlike most widgets in Composer, the necessary service creation and scripting must already exist in Transaction Manager before the widget can be added to the form.
The following discusses:
•Building an autoSuggest form element from scratch, with a service we have defined as ACME POST in Transaction Manager
•Using predefined widgets and scripts that ship with both Composer and Transaction Manager for the VEDA GeoCoder webservice
For further detail on the configuration parameters, refer to the notes below.
Another widget, the TM Reference Data Lookup Block, also provides lookup data. The aim of this widget is to give a convenient way to provide an auto suggest function with no programming. The reference data can be an Avoka Transact dynamic data service defined in TM (see the Transaction Manager Administration Guide), or from prepopulated data (see here for an example of how you introduce prepopulated data onto a form using a Data Field widget). In this example, we use test data.
The only change we made to the structure built from the block was to build the "Result" block (3 in-line text fields named according to the table headings of the CVS test data) and point to it in the "Configuration" panel. Note the "Complex Reference Data" checkbox: it is activated because the data is a table with more than 2 column headings.
Panels in "Properties -> Data" for the "Type" node (a TM Reference Data Lookup block)
Which results in the following behavior:
You can have only two columns of data, that is only one pair of data points per row separated by a single comma. Make sure the Complex Reference Data checkbox is unchecked.
So, as there are now no headings, the convention is that the left data point or column is refered to as "display". The right data point or column is called "data". The default parameters of the Configuration Panel is to have the left column, "display", as the "Trigger Field Name"; the right is the "Data Field Name".
Composer and Transaction Manager come with a preconfigured widget -- the "Transaction Manager -> TM Veda Address Lookup Block [Australia]" which contains associated address widgets and a preconfigured Auto Suggestion Controller; TM comes with the corresponding service definitions and Groovy scripts for accessing the Veda GeoConnect DDS. These provide an off-the-shelf, convenient way to construct autosuggest address fields, with two layers of dependent data.
The main node for configuring the widget is the "_controller" node under the "Veda" block, particularly the parameters under:
•the panels in "Properties -> Data"
•the four scripts under "Rules -> Click -> Click"
With these scripts and parameter settings, the behavior in a form is as follows:
Note: there is a service charge for each time the Veda AutoSuggest widget returns a value to the form (and not the number of times the DDS service is accessed to provide suggestions).
The following tables describes some of the "TM Auto Suggestion Controller" parameters and gives the default abstracted values provided off-the-shelf in the "TM Veda Address Lookup Block [Australia] -> _controller". If you want to change these values, you should do this in the TM Veda Address Lookup Block [Australia], not in its children.
Note: you still nominate to use test data in the "TM Veda Address Lookup [Australia] -> _controller -> Data -> Test Mode" checkbox.
This is a special checkbox in "TM Veda Address Lookup Block [Australia] -> Properties -> Data -> Veda Configuration": the "Hide Standard Address Block". Its behavior is as follows:
•When checked:
oInitally only the trigger field is visible and the address block invisible,
oIf the user selects one of the suggestions, the filled-in trigger field only is visible
oIf the user selects "My address is not listed", the address block becomes visible and the focus moves to "Address Line 1".
•When not checked:
oInitially, both the trigger field and the address block are visible
oInitially only the trigger field is writable
oIf the user selects "My address is not listed", the address block becomes writable and the focus moves to "Address Line 1".
•In both cases:
oThe trigger field will be cleared, regardless of the setting "_controller -> Clear Trigger Field When Not Matched".
Sequence numbers are enabled by these lines at the end of the service definition Groovy script in Transaction Manager:
// See if there is a queryString holding a sequence number
def value = request.getParameter("seq")
if (value == null || "".equals(value)) {
// The request parameter 'seq' was not present in the query string OR
// The request parameter 'seq' was present in the query string but has no value
return result
} else {
// add the sequence number back on the result
result += new JSONSerializer().toJSON("{'seq' : '" + value + "'}")
return result
}
If there have been a number of requests made on the DDS, the responses may not be returned in the same order as the requests. If sequence numbers are being emitted in response, the value of seq is incremented with each response, allowing TM to tell if responses came back out of sequence. TM will then only act on the most recent response, that with highest seq number.
End users on IE8 can receive multiple alert dialogs. The workaround for this is setting the "TM Auto Suggestion Controller -> Edit Properties -> Rules -> Click -> Failure Notification" and choose "Do Nothing".
