The Lookup Widget

Return to widget:type page to see list of all widget types. Back to fields.ini file to see other fields.ini directives.

Synopsis

The lookup widget allows users to look a record from another table to insert into the field. It is like a select widget except that it doesn't use a vocabulary. Instead you just specify a table on which it should search using the widget:table directive. In order to use the lookup widget to edit a field, you should set the widget:type directive of the fields.ini file for the field to lookup. I.e.

[fieldname]
    widget:type=lookup
    widget:table=mytable

Note that the lookup widget requires the widget:table? directive to be set to the target table of the lookup or it will not work properly.

Required Directives

The following fields.ini file directives are required to accompany the field definition if a lookup widget is used:

Optional Directives

The following additional optional directives may be used to customize the behaviour of the lookup widget:

widget:filters:-limit=100

widget:filters:-sort=category_name asc, year desc

widget:filters:country=Canada

widget:filters:country_id="$country_id"

See URL Conventions for an overview of the types of GET parameters Xataface can take. Any GET parameters that manipulate a query can be used with the widget:filters:* directive to modify the query results that are shown in the lookup widget.

Example

In this example we have a field named appointee that is supposed to reference the contacts table. So in the fields.ini file we would have:

[appointee]
    widget:type=lookup
    widget:table=contacts

Initially we just have a little find icon next to the field. If the user clicks it, a dialog pops up enabling them to search for the contact that they want:

Additional Tips

Although the lookup widget does not use a vocabulary as indicated in the Synopsis above, it is still useful to define a vocabulary in the fields.ini file for this field. The reason is because the lookup widget is only used with the edit action, where you are inserting or editing data into the field. However, it is not used to the display the data in the view or list actions. Therefore, you must still have a vocabulary defined to properly display these values.

In order to customize the display of the lookup widget's select list, you must edit the delegate class for the table which is referenced by the widget:table directive. There are two important points to note:

1. The items in the selection list are formatted based on the getTitle($record) delegate class function if it is defined. However, ...
2. The Search box will search on text in VARCHAR and TEXT fields. If you need to search for data in numeric fields, you can create a grafted field using a function such as CONCAT() to display numbers as text.

Note that the lookup widget makes heavy use of the RecordBrowser widget as defined in Xataface source code.

Links:

• Lookup widget on view with compound primary key