Forms
Show and submit forms built in the dashboard's form builder.
Quick start
One call: load a form and draw it
const container = document.getElementById('form');
if (container === null) {
throw new Error('Missing <div id="form"></div>');
}
await window.Portal.forms.initAndRender(container, 'FORM_REF', {
onSubmit: () => alert('Thanks!'),
onValidationError: (errors) => console.warn(errors),
});API reference
window.Portal.forms
Portal.forms — show and submit forms built in the dashboard's form builder.
init()
Loads a form's definition.
const formsInitResponse = await window.Portal.forms.init(reference_num);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The record's reference number. |
Returns
Resolves with a PortalFormsInitResponse: The answer to Portal.forms.init(): the form definition.
initAndRender()
Loads a form and draws it in one step.
await window.Portal.forms.initAndRender(container, reference_num, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
container | HTMLElement | Yes | The element to draw into. |
reference_num | string | Yes | The record's reference number. |
options | PortalFormsRenderOptions | No | Callbacks for rendering a form with renderForm() / initAndRender(). |
Returns
Resolves when the call has completed.
renderForm()
Draws an already loaded form (init().form) into container.
window.Portal.forms.renderForm(container, form, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
container | HTMLElement | Yes | Draws an already loaded form (init().form) into container. |
form | PortalFormsInitResponse['form'] | Yes | The answer to Portal.forms.init(): the form definition. |
options | PortalFormsRenderOptions | No | Callbacks for rendering a form with renderForm() / initAndRender(). |
submit()
Submits entered data to a form.
const formsSubmitResponse = await window.Portal.forms.submit(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | PortalFormsSubmitPayload | Yes | What Portal.forms.submit() sends. |
Returns
Resolves with a PortalFormsSubmitResponse: The answer to Portal.forms.submit().
Types
PortalFormsInitResponse
The answer to Portal.forms.init(): the form definition.
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the form exists and is published. |
form | object | Yes | The form definition. |
form.reference_num | string | Yes | The form's reference. |
form.name | string | Yes | Display name. |
form.version | number | No | The form's published version number. |
form.locales | string[] | No | The languages the form is translated into. |
form.json_data | unknown | Yes | The form's structure (fields, pages, rules). Opaque: hand it to renderForm(). |
PortalFormsRenderOptions
Callbacks for rendering a form with renderForm() / initAndRender().
| Name | Type | Required | Description |
|---|---|---|---|
onSubmit | (result: unknown) => void | No | Called with the server's answer after a successful submission. |
onError | (err: Error) => void | No | Called when loading or submitting fails. |
onValidationError | (errors: Record<string, string[]>) => void | No | Called when the server rejects the data; keys are field names, values their messages. |
PortalFormsSubmitPayload
What Portal.forms.submit() sends.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The form's reference. |
submission_data | Record<string, unknown> | Yes | Field name to entered value. |
idempotency_key | string | No | Any unique string; resubmitting with the same key will not create a duplicate. |
locale | string | No | The language the visitor used. |
duration_seconds | number | No | How long the visitor took, for analytics. |
PortalFormsSubmitResponse
The answer to Portal.forms.submit().
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the submission was stored. |
submission | object | Yes | The stored submission. |
submission.reference_num | string | Yes | The submission's reference. |
submission.form_reference_num | string | Yes | The form it belongs to. |
submission.created_at | string | Yes | ISO timestamp. |