Skip to content

Forms ​

Show and submit forms built in the dashboard's form builder.

Quick start ​

One call: load a form and draw it

ts
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.

ts
const formsInitResponse = await window.Portal.forms.init(reference_num);

Parameters

NameTypeRequiredDescription
reference_numstringYesThe 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.

ts
await window.Portal.forms.initAndRender(container, reference_num, options);

Parameters

NameTypeRequiredDescription
containerHTMLElementYesThe element to draw into.
reference_numstringYesThe record's reference number.
optionsPortalFormsRenderOptionsNoCallbacks for rendering a form with renderForm() / initAndRender().

Returns

Resolves when the call has completed.

renderForm() ​

Draws an already loaded form (init().form) into container.

ts
window.Portal.forms.renderForm(container, form, options);

Parameters

NameTypeRequiredDescription
containerHTMLElementYesDraws an already loaded form (init().form) into container.
formPortalFormsInitResponse['form']YesThe answer to Portal.forms.init(): the form definition.
optionsPortalFormsRenderOptionsNoCallbacks for rendering a form with renderForm() / initAndRender().

submit() ​

Submits entered data to a form.

ts
const formsSubmitResponse = await window.Portal.forms.submit(payload);

Parameters

NameTypeRequiredDescription
payloadPortalFormsSubmitPayloadYesWhat 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.

NameTypeRequiredDescription
successbooleanYesTrue when the form exists and is published.
formobjectYesThe form definition.
form.reference_numstringYesThe form's reference.
form.namestringYesDisplay name.
form.versionnumberNoThe form's published version number.
form.localesstring[]NoThe languages the form is translated into.
form.json_dataunknownYesThe form's structure (fields, pages, rules). Opaque: hand it to renderForm().

PortalFormsRenderOptions ​

Callbacks for rendering a form with renderForm() / initAndRender().

NameTypeRequiredDescription
onSubmit(result: unknown) => voidNoCalled with the server's answer after a successful submission.
onError(err: Error) => voidNoCalled when loading or submitting fails.
onValidationError(errors: Record<string, string[]>) => voidNoCalled when the server rejects the data; keys are field names, values their messages.

PortalFormsSubmitPayload ​

What Portal.forms.submit() sends.

NameTypeRequiredDescription
reference_numstringYesThe form's reference.
submission_dataRecord<string, unknown>YesField name to entered value.
idempotency_keystringNoAny unique string; resubmitting with the same key will not create a duplicate.
localestringNoThe language the visitor used.
duration_secondsnumberNoHow long the visitor took, for analytics.

PortalFormsSubmitResponse ​

The answer to Portal.forms.submit().

NameTypeRequiredDescription
successbooleanYesTrue when the submission was stored.
submissionobjectYesThe stored submission.
submission.reference_numstringYesThe submission's reference.
submission.form_reference_numstringYesThe form it belongs to.
submission.created_atstringYesISO timestamp.