- Auto Complete Properties

Auto Complete Properties

[PRO] Once you have an auto complete field configured, you can further customize it using an AutoComplete property group. WOW will look for AutoComplete properties first in the possible values operation for the auto complete field, then in the main query operation, and finally in the application. (AutoComplete properties can be specified in any of these locations, but properties in the possible value operation will take precedence over those in main operation, and properties in the application are overridden by properties from either of the other locations.)

The properties available in the AutoComplete property group are listed below. In general, you can use an AutoComplete field without setting any of these properties – you only need to specify them if you want to change the default setting.

• • cache timeout – The number of seconds items are retained in the special auto complete cache. This cache is intended to reduce the number of times WOW needs to query the database when the user is typing multiple characters at once. (For example, if we have already searched for states beginning with ‘M’ and a half second later we are now searching for states beginning with ‘Mi’, it will be quicker to search among the previously retrieved states than to run another database query.) The default is 15 seconds. (Setting this property to -1 will turn off the special auto complete cache.)

  • case sensitive – Whether or not the auto complete search is case sensitive. The default is false. Case sensitivity in auto complete searches also depends on the database connection settings for LIKE comparisons. If the connection setting does not match the auto complete setting, then auto complete searches will return inconsistent results.

  • count – The maximum number of values to display in the drop down. This defaults to the Row Count of the possible values operation. Using a higher Row Count can be beneficial since it allows WOW to retain more values in its cache, which can improve performance. So in some cases you may want WOW to read and cache more possible values than you want to display on the screen, which is why you would adjust the count property.

  • css – This is the CSS class which is used to display the drop down. The default value is “pjAutoComplete”.

  • focus – Whether or not the drop down can appear when the field gains focus, or if the user has to actually type in order for the drop down to appear. The default is false (meaning the user has to type) unless the min chars property is set to 0, in which case the focus property defaults to true. If the focus property is explicitly set, the min chars setting does not matter.

  • item css – The CSS class used to display individual items in the drop down list. (The items are rendered as HTML DIV elements). The default value is “pjACItem”.

  • highlight css – The CSS class used to display the highlighted item in the drop down list. (The items are rendered as HTML DIV elements). The default value is “pjACItemH”.

  • min chars – The minimum number of characters which must be present in the search field before the drop down is displayed. The default is 1. This property is related to the focus property.

  • strict – This is a comma separated list of modes where WOW will enforce strict possible value behavior on the auto complete field. When strict behavior is being enforced, WOW will display an error message if the user enters a value which is not among the possible values. The possible modes for this property are copy, edit, insert, and search. You can also use the special NONE value. If this property is not specified (or is left blank) WOW will enforce strict behavior in copy, edit, and insert modes.

  • strict message – This is the error message WOW will display when the user enters a value not among the possible values when strict behavior is being enforced. The default is "You must select a value from the drop down list"

  • search type – Specify "contains" if you want to be able to enter search characters at any location in the auto complete list. For example: typing "Dakota" will show both "North Dakota" and "South Dakota".

  • type - Specify "java" for small lists that can be read in once. Specify "sql" for large lists where an SQL statement will be executed as the user types each character to reduce the possible results.

Auto Complete Advanced Configuration

This section contains information on additional ways to configure and customize auto complete fields.

Formatted Display Value

In the previous example, we saw how an auto complete field handles display values differently than internal values. There is an optional third type of value, a “formatted display value” which can be used to display additional information in an auto complete drop down. For example, if the user is searching for accounts by state, we can use the drop down to show how many account are in each state, like this:

In this situation, each possible value contains 3 distinct values: the internal value (“MA”) which is used internally in database queries but never displayed; the display value (“Massachusetts”) which is shown in the search field; and the formatted display value (“Massachusetts 2 accts”) which is shown in the drop down.

There are two ways to use a formatted display value in the auto complete drop down. The first is to change your possible values query to return a third column of results. The third column should include any HTML formatting, and will be used as the display value. Here is the possible values query which produces the above auto complete drop down.

The third column in the query contains both data (the CNT value from the join table) as well as HTML formatting for displaying the data.

The second way to use a formatted display value involves creating a custom Row subclass in Java. If your custom Row subclass is used as the row class by the possible values query, then it should extend the planetj.dataengine.possiblevalues.AutoCompleteResultRow class. You can then override the getFormattedDropDownValue(ExecutingContext) method to supply the formatted display value for that result row.

When using a formatted display value, it is important to remember that the formatted display value is never shown in the auto complete field itself, only in the drop down. Therefore it is the display value (and not the formatted display value) that is plugged into the possible values query and determines which possible values should be displayed in the drop down.