Use Custom Form Container to collect user inputs

A Custom Form can be used to collect user inputs from other Form Elements. These inputs can then be used to perform a variety of actions, including to filter your data, run models, and write back to databases.

How does the Form Container work?

A Custom Form can contain multiple form elements, which the user will be able to interact with. This can include checkboxes, radio buttons, etc. Whenever a user interact with these elements, such as selecting an option or inputting a value, their input is sent to the nearest form.

When you create interactions on the form, you'll be able to access the values outputted by the user with the accessor ${event.form.item_name}.

What if there are nested forms?

If there are nested forms, inputs are sent to the nearest form.

In the example below, you'll see two nested forms. Form 1 will be able to access values for Input 1 and Input 2, while Form 2 only has access to Input 3. Since inputs are only sent to the nearest form, Form 1 will not be able to access Input 3.

How to create your form

  1. Drag a Custom Form onto your page.

Interactions to submit the form

Once the form has been set up, the last step is to create 2 interactions to be able to use the user-inputs.

  1. On the form: Trigger actions to perform when the form is submitted.

  2. On the submit button: Trigger the form to submit.

In this example, when the submit button is clicked, the form will be submitted and carry out the action.

What the form will do when it's submitted

  1. Select the form and add a supported Submit event.

  2. Create an action that will use the inputs the form has collected. For example, you can use the inputs to change SQL parameters.

  3. Access the user inputs from the the form's event payload using ${event.form.min_volume}.

Submitting the form

We've set up an interaction that tells the form what to do when it is submitted. However, the form will still need to be prompted to submit through an interaction on another element.

  1. On another element, such as a button, set up an interaction to submit the form by selecting Element -> Form -> Submit form as the action.

Last updated