Twitter Feed

Xataface Maillist

Sign up to receive the Xataface news letter with weekly updates and development tips.

Found 1 of 138 records in table Wiki
Now Showing 1 of 1

Current Record: lookup

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.


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.


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:

Name Description Version
widget:table The name of the table in which the lookup widget should look up related records. 1.0

Optional Directives

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

Name Description Version
widget:filters:-limit Sets the number of records that are shown by default in the lookup widget. Default is 30 if this is omitted. E.g.
to show 100 records at a time.
widget:filters:-sort Specifies the columns to sort the results on. E.g.
widget:filters:-sort=category_name asc, year desc
widget:filters:* Any valid Xataface directive can be used to filter the results by specifying widget:filters:param (where "param" is a valid Xataface GET parameter, which could include a column name to filter results on, or other filter directives).
To only show results with Country=Canada.
widget:filters:*=$* Dynamic filters. Causes the options in the record browser to be filtered on the value of another field in the form. e.g.
would show only results with records having country_id matching the value of the 'country_id' field in the current form.

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.


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:


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.


blog comments powered by Disqus
Powered by Xataface
(c) 2005-2018 All rights reserved