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.

2. Build your layout, including Form Elements, inside of the form. This example contains an Input, Radio Button, and Multiselect.
3. Set the form item name for each form element. This is the name that the form will use to access the user input. For example, this element has a form item name min_volume. In an interaction on the form, it will be accessed through ${event.form.min_volume}.
4. Configure each element. In the example above, we want to the min_volume input to be a number, so we set the input type to number. Other elements may require you to set a list of options for the user to choose from. For example, this radio button gives users 3 options to choose from. In each pair of inputs, the top value is the value returned by the element and sent to the form. The bottom is the display name. Other elements, such as the multiselect, will return an array of selected values. See each element's page for more details on how it is configured and how values are outputted.

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.