Form
Embed a form for the user to fill in as a new Record, or open an existing Record to edit or view.
The Form widget shows one form. When the user submits, the widget saves a Record in the form's table and tells your page. The rest of the contract (credential, ready, error) is in Widgets.
URL and parameters
The URL is <site>/widgets/form. A boolean is written true or false.
| Parameter | Meaning | Required |
|---|---|---|
item_id | The id of the form Item, or of a table Item. For a table, the widget builds the form from the fields that are visible and editable. | Yes |
data_id | The id of the Record to open for editing. Without it the form creates a new Record. | No |
selectable | true adds a field where the user picks the Record to edit. It appears when the form allows editing data and the user may update data. Default false. | No |
cancelable | Show the close and cancel buttons. Default true. | No |
readonly | true shows the values without editing and without a submit button. Default false. | No |
embedded | true removes the border and spacing around the form so it fits the frame you embed it in. Default false. | No |
hide_header | true hides the name and the description of the form. Default false. | No |
Messages
| action | Direction | Payload |
|---|---|---|
submitted | widget to your page | None. Sent after the server has saved the Record. |
cancel | widget to your page | None. Sent when the user presses the close or cancel button, including the one on the page that says the form could not be loaded. |
error | widget to your page | { statusCode } when the Item cannot be read, for example 403 or 404. |
This widget takes no post-widget-parameters, so it sends no ready. It can be used as soon as the iframe has loaded.
submitted does not carry the id of the Record. If you need it, read it through the API or make the id yourself.
After a successful submit the widget shows a success message and a button to fill in again (when there is no data_id). The widget does not close itself. Your page removes the iframe.
Example
Continuing the example in Widgets, change the widget name to form, set item_id, and listen to the form's messages.
addEventListener('message', (e) => {
if (e.origin !== site || e.data.messageToken !== messageToken) return
if (e.data.action === 'submitted') frame.remove()
if (e.data.action === 'cancel') frame.remove()
})Notes
A geometry field of the form is shown as a geometry editor field inside the form. You do not embed it again. What the user draws goes with the Record that is submitted.