Form Configuration Options

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:

• Liquid
• Using Forms

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.

The configuration part of the form, in between the tags written on lines #1 and #42, defines the API endpoint where the server listens to specific requests and invokes all actions defined in the form.

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 or . Some examples:

• 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 as an identifier by default and as an override.

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 Template code executed asynchronously. No timeout is set for processing this code, so it is the right place for time-consuming 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:

Keep them in mind when writing code so that it runs fast enough for its priority.

Example:

authorization_policies

Array; contains a list of names of Permissions that guard against unauthorised submissions.

request_allowed

Boolean; controls whether a form will be available as an endpoint (which is deprecated). If , the form will be usable only through GraphQL mutation. The default is .

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 variable and has the following configuration options:

• - Used to ensure 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:

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.

sms_notifications

Array; text message notification names executed after the form is successfully submitted.

api_call_notifications

Array; API Call Notification names executed after the form is successfully submitted.

flash_alert

String; message that is passed to the object when the form validation is raised. This message is usually used to warn users about some errors and is used by the system only if form submission fails.

flash_notice

String; message that is passed to the object when the form is valid. This type of message is usually used to notify the user about the success of an operation and is used by the system only if the form submission succeeds.

redirect_to

String; defines the page path rendered after successful form submission. Example: . You can use Liquid to determine what the value should be. This property can also be set up during form submission by setting the value of the parameter. For example, you can have two submit buttons in your form, with different values to send the user to other places depending on which one has been clicked.

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:

resource_owner

String; defines the user permissions schema of the form configuration.

Available values are:

• - anyone can modify the object
• - only the user that previously 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:

This configuration option is very useful when you restrict user permissions to allow certain users to modify only the records they previously created.

spam_protection

Object, strategy and configuration for strategy. There are available strategies and

Config for :

Config for :