Auto-complete for reference fields

By default, a reference field auto-completes as the user types in the field.

Administrators can configure additional auto-complete options. A user must have table-level read permission on the referenced table for auto-complete to display any options.
Figure 1. Auto complete

Dictionary attributes for auto-completion of reference fields

There are dictionary attributes that are specific to reference fields and that determine auto-complete behavior.

Table 1. Reference field auto-completion dictionary attributes
Attribute Description
ref_auto_completer Specifies the name of the client-side JavaScript class that creates the drop-down auto completion choices. Valid class values include:
  • AJAXReferenceCompleter: Displays matching auto-complete choices as a drop-down choice list. The list only displays the reference table's display value column. Reference fields automatically use this class if there is no other auto-completion class specified.
  • AJAXTableCompleter: Displays matching auto-complete choices as rows in a table. The table displays the reference table's display value column and any columns listed in the ref_ac_columns attribute.
  • AJAXReferenceChoice: Displays matching auto-complete choices as a drop-down choice-list. The list only displays the reference table's display value column. Furthermore, the list only displays up to 25 matching choices. If there are more than 25 auto-complete choices, the reference field instead displays the choices with the AJAXTableCompleter class.
ref_ac_columns Specifies the list of reference table columns to display. Separate column names with a semi-colon. For example, ref_ac_columns=user_name;email;sys_created_on allows auto-complete to match text from the user_name, email, and sys_created_on columns.
ref_ac_columns_search Enables auto-complete to match text in the columns listed in the ref_ac_columns attribute. Set this attribute to true to enable auto-complete to match text in all reference field columns. By default (or when this attribute is false) auto-complete only matches text in the display value column.
ref_ac_order_by Specifies the reference table column that sorts the auto-completion choices. For example, ref_ac_order_by=name sorts the auto-completion choices alphabetically by name.

Administrators can also set a user preference to use a contains auto-complete search.

Auto-complete UI features

The AJAX table completer class has a number of UI improvements.

  • The table completer always displays the number of records the auto-complete query finds.
  • The table completer highlights the entire selected row by changing the color of the background and text.
  • The table completer lists a value for every column.
    • The first time a value appears in a column, the table completer displays it in black text.
    • The table completer displays subsequent duplicate values in grey text. Previously, the table completer displayed an empty cell in a column containing a duplicate value.
Figure 2. Selected row highlight

Set the ref_auto_completer=AJAXTableCompleter dictionary attribute to use these improvements.