DevelopWidgets
Data picker
Lets the user pick Records from a table or from the lookup data of a form. The result comes back as the message select with the Records that were picked.
The data-picker widget lets the user search, filter and pick one Record or several, and sends the picked Records back to your page.
URL and parameters
The widget is at <site>/widgets/data-picker. The parameters every widget takes are in Widgets.
| Parameter | Meaning | Required |
|---|---|---|
item_id | The _id of the table or form that holds the data. | Yes |
data_lookup_field | The name of a field in item_id that points to lookup data. If set, the widget shows that lookup data (columns code and description) instead of the Records of item_id. | No |
value_field, text_field | The names of two fields of the table. Set both and the widget shows the text_field column only and returns only these two fields. Setting just one has no effect. | No |
single_select | true allows one Record. The default is false. | No |
disabled_rows | Values that cannot be picked, separated by commas. Compared with value_field if you use value_field, with code if you use data_lookup_field, and with _id otherwise. | No |
Messages
| action | Direction | payload |
|---|---|---|
select | widget to your page | { items }, an array of the picked Records. Each one is an object of fields. It is an array even when one Record is picked. |
cancel | widget to your page | None. The user closed it without picking. |
This widget does not send ready and does not read post-widget-parameters. Put every value in the URL. It sends error and close-with-error as in Widgets.
Example
embedParams is the common parameters from Widgets.
const params = new URLSearchParams({
...embedParams,
item_id: tableId,
single_select: 'true',
})
frame.src = `${site}/widgets/data-picker?${params}`
addEventListener('message', (e) => {
if (e.origin !== site || e.data.messageToken !== messageToken) return
if (e.data.action === 'select') useRecords(e.data.payload.items)
})