Auto-Complete Functionality

Owned by Brian May
Last updated: Feb 08, 2024 by Matt Denninghoff
6 min read

Auto-complete, also referred to as auto-suggest, is a feature that suggests values in a dropdown list as you type into a textbox. In Profound UI, textbox widgets have a set of auto-complete properties that can either provide a static suggestion list or link to a database for suggestions.

To enable scrolling for the auto-complete choices, you must specify the 'max height' property for the textbox.



Auto-Complete Choices

These properties allow you to provide a static or program provided list of auto-complete choices.

Choices

Specifies the options for a textbox with auto-complete. The options should be comma separated. The first option cannot be empty.
Promptable? YES
Possible Values: Comma separated list of valid choices
Bindable? YES
Product: Profound UI, Genie

Choice Values

Specifies alternate option values to send to the application for a textbox with auto-complete. The values should be comma separated. The first option cannot be empty.
Promptable? YES
Possible Values: Comma separated list of valid values to be returned to application.
Bindable? YES
Product: Profound UI, Genie

Database-Driven Auto-Complete

These properties allow you to provide the needed information to retrieve the list of auto-complete choices from a database file.

Choices Database File

Database file to be used for a dynamic database-driven textbox with auto-complete.
Promptable? NO
Possible Values: Any valid database file name. Can be specified with library in 'LIBRARY/FILE' format.
Bindable? YES
Product: Profound UI, Genie

Choice Options Field

Database field name used to retrieve the options for a textbox with autocomplete. Multiple fields can be specified and should be comma separated.
Promptable? YES
Possible Values: Any valid database field name(s) from the Choices Database File
Bindable? YES
Product: Profound UI, Genie

Choice Values Field

Database field name used to retrieve the values sent back to the application. If omitted, the choice options field is used. If multiple option fields were specified, the first option field is returned.
Promptable? YES
Possible Values: Any valid database field name from the Choices Database File
Bindable? YES
Product: Profound UI, Genie

Choices Selection Criteria

Optional expression identifying which records should be retrieved from the choices database file.
Promptable? YES
Possible Values: Any valid selection criteria for the Choices Database File. Selection criteria should be formatted like a SQL "Where" clause.
Bindable? YES
Product: Profound UI, Genie

Choices Parameter Value

Value used for parameter markers specified in the 'Choices Selection Criteria' property. Parameter markers are specified in 'Choices Selection Criteria' by using a question mark ( ? ). 
Promptable? YES
Possible Values: Any valid value that can be used as a parameter for an SQL "Where" clause. 
Bindable? YES
Product: Profound UI, Genie

Max Choices

Optional maximum number of choices to provide for auto-complete. This property controls the size of the auto-complete dropdown list. If not set it defaults to 10.
Promptable? NO
Possible Values: Any positive integer value
Bindable? YES
Product: Profound UI, Genie

Contains Match

When set to true, the auto-complete query finds records that contain the search text. When set to false, the auto-complete query finds records that start with the search text. The default is false.
Promptable? DROPDOWN
Possible Values: True, False
Bindable? YES
Product: Profound UI, Genie

Case Sensitive

When set to true, the auto-complete query does not convert the search text or database search column to upper case before comparing. When false, the database column and search text are converted to upper case before comparing. The default is false.
Promptable? DROPDOWN
Possible Values: True, False
Bindable? YES
Product: Profound UI, Genie

Dynamic Auto-Complete

This method allows auto-complete choices to be retrieved from a web service.

Choices URL

Sets the URL to a Web service that returns the choice options and values in JSON format. If a choices URL is used, then the database file, choice options field, choice value field, and max choices properties are ignored. An HTTP POST parameter named "query" is automatically submitted to the URL that contains the current contents of the widget that is using this property; the “query” value is updated every time a request to the URL is made such as on every keystroke within the widget.

The Web service can be provided with Profound.js, Profound Logic's RPGsp, or another web development framework. Profound.js provides very simple tools including low-code for developing Web services on most platforms.
Promptable? YES
Possible Values: A valid web service URL
Bindable? YES
Product: Profound UI, Genie, Profound.js

 

Use Choices URL For Reverse Lookup

Normally, the choices URL is called when a user types text into the textbox.  If this property is enabled, it will also be called as a "reverse query" when the screen is loaded.  In this scenario, it will be used to look up the choice text for the field that is bound to the value property. Unlike a standard (forward) lookup, when a reverse lookup is run the "query" parameter is not sent.  Instead, a parameter named "reverse" will be set to 1 to indicate that a reverse lookup is in progress, and a parameter named "value" will provide the value that was bound to the widget.

Promptable? YES
Possible Values: true or false
Bindable? YES, indicator
Product: Profound UI, Genie, Profound.js

 

 

JSON Format To Be Returned By Choices URL Web Service

A “choices url” web service should provide its forward and reverse lookup responses in this JSON format:

{ "success":true, "errorId":"-999", "errorText":"One-line error message here", "errorText2":"Long, paragraphs of detailed error message here.", "response": { "valueField": "FIELD2", "results":[ {"FIELD1":"XXXXX", "FIELD2":"YYYYY", "FIELD3":"ZZZZZ"}, {"FIELD1":"AAAAA", "FIELD2":"BBBBB", "FIELD3":"CCCCC"} ], "colWidths": [ 80, 70, 60 ] } }

  • success = Required. Must be true/false to indicate whether the lookup was successful, or whether there was an error

  • errorId, errorText, errorText2 = Required if success=false. Ignored if success=true. Describes the error that has occurred.

    • errorId = A number or code that identifies the error. Examples: "CPF1234", "-12944"

    • errorText = A one-line human-readable message. Example: "File not found"

    • errorText2 = A longer description/discussion of the message. Example: "The file FOO was not found in your BAR directory. If you were not expecting this, you should contact your system administrator and give code -12944 to let them know about the problem"

  • response = Required when success=true. Ignored when success=false. Contains the successful response.

    • valueField = Optional. Denotes one field name from the "results" listing below that represents the value of a choice (vs the displayed text).

      • IMPORTANT: the order that the fields are defined in the result records matters when “valueField” is set--the first field will be used as the displayed text.

    • results = Required when success=true. List of results to show in the auto-complete choices.

      • The field names are user-defined. The names do not matter to Profound UI, but you will need to know what they are for the "valueField" option as well as the "results template" property.

      • You can have any number of fields in each row of results. If you use the "results template" property, you can format how these fields are used. If "results template" is not specified, all of the fields aside from the valueField will be shown concatenated into the choices results.

    • colWidths = Optional. Array indicating the size of each column in pixels for the choices results. If not specified, 100 will be used for each column.

 

The following variables are sent to the choices url (as url-encoded form data sent in a POST request):

  • AUTH = Only in Profound UI. Profound UI session id

  • workspace_id = Only in Profound.js Spaces. Represents the workspace id.

  • reverse = Specified only for reverse lookups. Set to 1 for reverse lookup, unset otherwise.

  • value = Specified only for reverse lookups. Set to the value that the choice text is needed for.

  • limit = The maximum number of "results" that are expected.

  • query = Characters typed into box to query for. Not provided for reverse lookups.

Click here for an example of writing a choices url web service in RPG using the Profound UI universal display interface.

 

Results Template

This optional template defines how returned fields display in the auto-complete drop down. Any text surrounded by parentheses that matches field names in the results gets replaced with the value from the results. If a template is not defined, then each row displays the value of the first field in the response.result record, even if multiple fields are in the record.

Autocomplete results may include multiple fields per record, such as text to display to the user and an ID for the application to use. In such a case a “valueField” property would exist in the JSON returned by the web service. In order to display the text from the multiple fields, use the “results template” property.

 

For example, for result records that include two properties, “id” and “text”, a results template may defined like below:

<div class="autocomplete-item">(id) -- (text)</div>

Which could render like in the below picture:

image-20240208-225122.png

 

Events

Onselect

Initiates a client-side script when a selection is made from the selection list of an auto-complete textbox or a combo box. In the case of an auto-complete textbox, the selected record is passed to the function as a JSON object that has properties named after the selected fields.
Promptable? YES
Possible Values: Any valid JavaScript code
Bindable? YES
Product: Profound UI, Genie