Form
This article introduces you to our custom Form and its core features.
The Form app is deployed to customer servers per request. To learn more contact our support at [email protected]!
This custom app is under active development and any information in this documentation could be inaccurate or outdated!
If you have any questions please contact our support at [email protected]
What is Form?
With the Form custom app you can create highly customizable forms that you can deploy to various kiosk interfaces to collect the necessary information from people. You can fully tailor the 20+ available input types to your needs whether you want to collect information during an ordering process, collect email addresses for a newsletter or just simply create a customer feedback form.
Prerequisites
The first thing to do is to give a name to the form. This name will be used to identify this specific form.
While there is nothing to prevent naming two different forms the same name, doing it on the same page is highly unrecommended. Could cause errors.
To fully utilize the functions of the Form app you first need to create a mock datasource that will serve as a "virtual database" so all data submitted via the forms can be
stored or passed over to a third party system. To create a mock datasource navigate to Content > Base data path > Edit mock datasources. You can create a more complex structure
or just use a simple {"fields":[]} json data format.
Values are stored as text or number, images are stored in base64. If you choose to use complex export type, ALL parameters from the form widget will be stored like minimum/maximum range along with the actual value provided by the user.
The Form app works without datasource, but that also means it won't store its value anywhere, other than the widgets own value.
Setting up the widget
After creating the mock datasource you need to select a form widget and bind a datasource as output.
- Form output: This is the mock datasource your form outputs all its data into.
What to do with the collected data?
The collected data can be passed onto a third party system or inserted into an internal datasource.
- To send the data to a third party set up a Call API action with the POST method and specify the name of your mock datasource in a Data field. Some useful third party services we recommend for processing your data and creating automations: N8N, Google Apps Script.
- To insert your data into a datasource create an Insert to internal datasource array action.
Collecting and validating a form
A complete form is built from several field widgets placed on the same page. There is no single "form container" widget; each input (text, radio, date, and so on) is its own widget instance. They work together through a shared output datasource.
How multiple widgets gather their data
Bind every field widget's Form output to the same mock datasource. Each field writes its value into that datasource's Form collection under its own Name:
- A field only writes when placed on a live displayer (not in the editor).
- Writing is an insert-or-update keyed by the field's Name, so every field keeps its own entry and the widgets never overwrite each other. The result is a single record containing one entry per field.
- The shape of each entry depends on the Export type: Simple stores just the value under the field name; Complex stores the value plus the field's properties, settings, and a
lastModifiedtimestamp.
Because they all share one datasource, a Call API or Insert to internal datasource array action pointed at that datasource submits the whole form at once.
Fields are identified by their Name. Two fields sharing a name on the same page will overwrite each other in the output datasource. Always give each field a distinct Name.
How entries are validated
Validation is per field and opt-in:
- Enable Validate Field on each field you want validated (see Common Settings). What counts as valid is type-specific: for example, Email checks the address format, Number and Text check the value against a min/max range, and Radio, Checkbox, and Dropdown check the selection against options tagged as correct (
[!]). - When a validated field evaluates its value, it emits a
{FIELD-NAME}-validsensor event carryingtrueorfalse. - Enable Show Validation (in the Error settings) to also show a valid/invalid border, and Show error messages to display the reason for the types that produce one.
To react to the validity of the entire form (for example, to only enable a submit or Call API action when every field is valid), listen to each field's {FIELD-NAME}-valid sensor event and combine them with conditions. Do not rely on the FormSummary object for this: because each field widget is an isolated instance, FormSummary only reflects the most recently validated field, not the whole form. See Form summary for details.
Common settings
Every field type shares a common set of settings and behaviors (name, validation, export type, fonts, errors, speech-to-text and localisation). These are documented once here:
Form types
There are over 20 Form types you could choose from, grouped below by purpose.