Developers · Forms
Form Configuration Options
Last updated 7 November 2026
This document provides an overview of all form configuration options.
Prerequisites
To be able to follow this topic, you must first understand the following subjects:
Form example
The code below presents all possible form configuration options and the optional form implementation part after the YAML section. All possible configuration options will be explained in detail in the following section.
---
name: full_form_example
resource: example_record
resource_owner: anyone
redirect_to: /full-form-example
flash_alert: This is a flash alert (fail)
flash_notice: This is flash notice (success)
spam_protection: "" # e.g. { recaptcha_v2: {} } - needs to be configured
fields:
properties:
email:
validation:
presence:
message: Email cannot be empty
email: true
greeting:
property_options:
virtual: true
email_notifications:
- welcome_user
api_call_notifications:
- ping_example_com_on_user_sign_up
sms_notifications:
- welcome_user
callback_actions: >
{% log "Hello from callback actions" %}
async_callback_actions:
delay: 1
priority: low
max_attempts: 2
content: |-
{% log "Hello from async callback actions - I am delayed 1 minute!" %}
authorization_policies:
- valid_example_policy
default_payload: |-
{
"properties_attributes": {
"greeting": "Hello from default payload!"
}
}
---
<p>{{ form.fields.properties.greeting.value }}</p>
{% form html-class: "my-form" %}
<label for="form_email">Email</label>
<input
id="form_email"
type="email"
name="{{ form.fields.properties.email.name }}"
value="{{ form.fields.properties.email.value }}"
>
<p class="field-error"> {{ form.errors["properties.email"] }}</p>
</div>
<button>Save</button>
{% endform %}The configuration part of the form, in between the
The implementation part is displayed as HTML to your user. It is optional because sometimes you only want to configure the server, and the request will come from another source, like in the example tutorial from Building a Contact Form.
Required form configuration options
There is only one required form configuration option which is
resource
Use this option to indicate the name of your
-
Minimal form example
This example demonstrates the usage of a dynamic resource from a Table.
-
Creating a Sign-Up Form
This example demonstrates the usage of a pre-defined class resource.
Optional form configuration options
This section details the various optional form configuration options on Insites.
name
To reference your form in other places, you need an identifier - Insites use
For app/forms/full_form_example.liquid - the part marked out in bold is the default name (physical_file_path).
If you set it to something else, the new value becomes the new name for your form. It is recommended to leave this setting at default; that way, you can always tell your form's name from the file location.
Remember that all the module naming rules apply if you are referencing a form inside a module.
async_callback_actions
Asynchronous actions that run in a background job. This action does not block or halt the execution of the program flow, nor does it slow down the response to the user. This option accepts the following parameters:
- String; Liquid code that runs in a background job. It does not slow down the response to the user. It still has a time limit, set by (see the table below). Use for long calculations. - Integer; the number of minutes added to the moment of form submission before the code defined in is executed. - String; , or , defines the priority of execution when executed simultaneously with other callbacks. - Integer, number of executions of callback in case of an error, default is 1.
Priority timeouts:
| Priority | Timeout |
|---|---|
| high | 1 minute |
| default | 5 minutes |
| low | 4 hours |
Keep them in mind when writing code so that it runs fast enough for its priority.
Example:
async_callback_actions:
delay: 1
priority: low
max_attempts: 2
content: >
{% log "Hello from background" %}authorization_policies
Array; a list of authorization policy names that guard against unauthorized submissions.
callback_actions
String; Liquid Template code that is executed synchronously (slows down the response to the user) as soon as the form is successfully validated.
fields
Object; fields allowed to be passed to the form object and validation rules for each defined field. Every property added to the configuration is accessible in the
-
- Ensures that only valid data is saved into your database.
property_options
-
- Virtual fields come in handy when there’s no direct mapping to a record attribute or when you plan on displaying a value without processing.
Example:
fields: my_first_virtual_property: property_options: virtual: true
default_payload
JSON-formatted String; this option is merged with user data provided in the form submission.
email_notifications
Array; email notification names executed after the form is successfully submitted.
email_notifications:
- welcome_usersms_notifications
Array; text message notification names executed after the form is successfully submitted.
sms_notifications:
- welcome_userapi_call_notifications
Array; API Call Notification names executed after the form is successfully submitted.
api_call_notifications:
- ping_example_com_on_user_sign_upflash_alert
String; message that is passed to the
flash_notice
String; message that is passed to the
redirect_to
String; defines the page path rendered after successful form submission. Example:
For example, onboarding step 3 could have this code if it were preferred to save the progress (by submitting a form) the user made on the form and go back/forward afterwards:
<button name="redirect_to" value="/onboarding/step2">Back</button>
<button name="redirect_to" value="/onboarding/step4">Next</button>resource_owner
String; defines the user permissions schema of the form configuration.
Available values are:
- anyone can modify the object - only the user that created the object can update/delete the object with that form configuration - similar to for the User resource
The table below shows all possible resource owners for different resources:
| Resource | Available resource owners |
|---|---|
| User | self, anyone |
| Record | creator, anyone |
This configuration option is very useful when you restrict user permissions to allow certain users to modify only the records they created.
spam_protection
Object; the strategy and its configuration. The available strategies are
Config for
spam_protection:
recaptcha_v2:Config for
spam_protection:
recaptcha_v3:
action: signup # required, action for recaptcha V3
minimum_score: 0.5 # optional, minimum score that the system accepts for recaptcha V3, default: 0.5