AUTOSUGGEST (Adelia Web Context)

Object containing an editable text box and offering input assistance by proposing a list of results matching the text entered by the user in real-time.

The object is comprised of two graphical components:

• an entry field,

• a list of result values displayed dynamically below the entry field, similar to a combo. The result values are displayed vertically, one below the other.

Real-time input assistance means that the results list if progressively "refined" as the user enters text.

The correspondence between the string entered and the set of result values is defined according to a selection criterion.

By default, three predefined criteria are available:

• "starts with": the string entered corresponds to the start of all result values in the list.
• "ends with": the string entered corresponds to the end of all result values in the list.
• "contains": the string entered is a sub-string of all result values in the list.

The set of result values is defined by a list (ordered set of values): In Adelia terms, the object is associated with a LIST.

The object proposes two modes of association:

• Combo box mode: Visually, the associated list is a single-column list. This list cannot be directly laid out in Dreamweaver (similar to the COMBO object). In terms of 4GL code, the Autosuggest object provides the properties VALUE, CURRENT_VALUE and LIST. It can be manipulated in the same manner as a COMBO BOX.
• Table list mode: The object is associated with a TABLE LIST object. Results rendering is linked to the rendering of this object (table with header, cell rendering according to the Adelia object types comprising the list's columns, etc.). Visually, the results list can be displayed in multi-column format. In terms of 4GL code, the Autosuggest object provides only the VALUE property. The LIST property does not exist in this mode, as the object is based on the list of the associated TABLE LIST object. To determine the values associated with the VALUE property, the user must select a "value" column amongst the columns making up the TABLE LIST.

The first mode is intended for rapid layout design with relatively simple data. The second mode, on the other hand, is used to design layouts containing more complex data to display (in guide style).

In both of these modes, the text entered into the entry field corresponds to the value of the Autosuggest object. Selecting an element in the associated list places its value in the entry field and, consequently, modifies the object's value.

Click below for further information about:

• Value-related text management

• Object typing

• Values in extreme cases

• Correlation between the VALUE and TEXT_VALUE properties

• Results list calculation

• Notion of performance

• Using the Autosuggest object with keyboard shortcuts

• Graphical properties of the Autosuggest object

• Classes of CSS styles

Value-related text management

In a similar manner to the COMBO BOX object's "explicit value-related text" feature, value-related text / value pairs can be managed in the associated list.

In this case, the results list is calculated by applying the selection criterion to the list element value-related texts.

Moreover, the text entered by the user in the entry field must be a value-related text (not a value). The text entered corresponds to a value-related text present in the associated list, whereas the value of the Autosuggest object is derived from the corresponding value-related text / value pair.

In Combo box mode, enabling value-related text management means that only the "value-related text" is displayed in the list (the "value" datum is hidden from the user).

In Table list mode, value-related text management is enabled by choosing a "value-related text" column from the columns making up the TABLE LIST object (the user decides whether the "value" column should be displayed).

If this management is enabled, then in both modes, the object proposes the TEXT_VALUE property, used to retrieve the text entered by the user.

Moreover, in Combo box mode, the object proposes the CURRENT_TEXT property used to associate a specific value-related text with an element in the list.

Object typing

The Autosuggest object is associated with an Adelia type.

It the object provides value-related text support, then it manages two Adelia types:

• one type for the value-related text: the user will only be allowed to enter values corresponding to this Adelia type into this entry field (via input control),
• one type for the returned value: this value's type may differ from the first.

Below are two summary tables of supported Adelia types according to Autosuggest object operating mode.

Values in extreme cases

When the Autosuggest object supports a value-related text, what value should this object assign to its VALUE property when:

• the results list is empty,
• no element is selected in the results list,
• the entry field is blank,
• the user entered a value into the entry field before the results list was displayed,

In these various situations, the user can specify a value to use according to the Adelia type of the Autosuggest object's VALUE property:

Correlation between the VALUE and TEXT_VALUE properties

If the Autosuggest object supports a value-related text, the values of these two properties are linked:

• If the user enter a value-related text present in the results list, the object's value is that of the value / value-related text pair,
• If the user enter a value-related text not present in the results list, the object takes a special value.

When manipulating these two properties within the 4GL, updating one of these properties triggers an update of the other:

Results list calculation

The results list is calculated by applying the selection criterion to the LIST object associated with the Autosuggest object. This process is triggered when the user enters text in the entry field.

Calculation may be performed automatically, or manually:

• automatic: The object calculates the result in a completely transparent manner for the user. The list is scanned in its entirety and if a LIST object element meets the criterion, then it is selected (in the *SELECT sense).
• manual: The user selects the elements to be included in the results list by populating the associated list. He/she can thus implement his/her own selection criterion. At the end of this process, all elements in the associated LIST object are included in the results list.

The results list is calculated in the Autosuggest object's ONSUGGEST Ajax event processing block.

Automatic mode is the default mode. Manual mode is enabled in code, by setting AUTOMATIC_MODE to *FALSE. If this property is *TRUE, then the 4GL code in the ONSUGGEST block is not run.

Notion of performance

For reasons of performance, the results list is calculated once the user has finished modifying the entered text (i.e. a given lapse of time after the last key press), not each time the user presses a key.

Several actions let you influence the results list display time:

• Define the minimum number of characters entered beyond which the ONSUGGEST event processing block is triggered (default value = 1).
• Limit the number of result values to display by defining a maximum number of results list elements to return. By default, all results list elements are displayed.
• In manual mode, optimize the result value search algorithm by working on a sorted list, if possible.
• Use cache management in the Autosuggest object: the object can store previous results lists to avoid launching a new query on each request.
• Enable the "case-sensitive" and "accent-sensitive" features when possible (if the input control linked to the Autosuggest field is "All upper case" or "Numeric" for example).

Using the Autosuggest object with keyboard shortcuts

The following actions are available for manipulating the object with the keyboard:

• Close the results list with the escape key. Similarly, if the user deletes the contents of the entry field, the results list closes.
• Change the selected element with the Up / Down or Page Up / Page Down keys (same effects as moving the mouse cursor to the text of an element).
• Retrieve the selected element to the entry field via the Enter, Tab or right arrow keys (same effect as clicking on the element). The results list closes.
• Place the cursor in the entry field when in selection mode on an element, via the Home key. The results list remains visible.

The Autosuggest object possesses a certain number of characteristics that define its operation:

In addition to its graphical properties, the Autosuggest object used a certain number of predefined CSS styles (in the AWSGUIControls.jsp style sheet located in the AWSResources directory).

When there are several Autosuggest objects (on a same page, or in various parts of a single layout), the general classes can be overloaded in order to assign different attribute values to each object.

Depending on the tag to which the tag is assigned, proceed as follows:

For each class whose tag ID attribute value is known, the named class corresponding to the ID value must be used.

If the named class overloads an attribute already defined in a general class, this attribute must be characterized with !important.

Example:

.AWSAutosuggestDiv { /* class used by all Autosuggest objects of the page */

   background-color:#0A0B0C;

}

#divAsgASG_2 { /* class used only by Autosuggest object ASG_2 */

   background-color:#334455 !important;

}

For a better understanding of the graphical functions for this object, please refer to the examples provided in the Adelia knowledge base (in the EXAMPLE_WEB application area in the KLBADEL environment).

Click below for more details on:

• properties,

• methods,

• events.

↑ Top of page