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.'''
The following fields.ini file directives are required to accompany the field definition if a lookup widget is used:
The name of the table in which the lookup widget should look up related records.
The following additional optional directives may be used to customize the behaviour of the lookup widget:
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.
Specifies the columns to sort the results on. E.g.
widget:filters:-sort=category_name asc, year desc
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.
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:
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:
The items in the selection list are formatted based on the getTitle(&$record) delegate class function if it is defined. However, ...
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.