# Forms
One of the most demanted features in any platforms is the ability to capture of user data, analyze it, and use it for segmentation. With this tool you can create as many forms as you need to collect data from the users of your sites.
When you access the tool, you can see a list of all the forms currently active in the account. You can filter by their status (enabled or disabled), by the site they're deployed to, and search by the name of the form.
In each row of the forms table, the columns are ordered by the name of the form, the date it was created, and the number of responses that were submitted for that form.
From this list, clicking the name of a form or its number of responses takes you to the form's Answers view.
In that view, the options menu in the upper right section lets you open the form on the site (View), if it is enabled; edit it (Edit); enable or disable it (Enable or Disable) to allow users to send their answers or not; and delete it (Delete). Editing, enabling, disabling, and deleting require the Admin Forms permission; without it, the menu shows Show instead of Edit, to see the form's settings.
Danger
To delete a form, you must disable it first. When you confirm, all its data is permanently deleted, including its answers. You also can't delete a form that is used in a segment.
# Create a form
To create a new form, follow these steps:
- From the side menu in the platform, select Customers, and click Realms.
- Click on your realm.
- Click New Form. This will take you to the creation view of a new form, where you must fill in the main attributes of the form:
- Name: Name associated with the form. This value will appear both in the form index in the Modyo administrator and as a title when a user is responding to it.
- Description: This text will appear as text below the title when users respond to it.
- People limit: Allows you to determine the maximum number of answers allowed.
- Site: Allows you to select where this form will be displayed. Keep in mind that this causes the form to change its appearance according to the classes defined in the site's global CSS. For more information, go to Template builder.
Alert
You can only select a site that belongs to the same realm, within the Site Settings, under General, make sure that the site is part of the correct realm.
Forms copied to a realm stage arrive without a site. Until they have one, the forms list shows an icon next to their name with the notice This form has no web app assigned.
- Enabled: Select if the form will start in an enabled state or not.
- Accept multiple answers: If this option is enabled, each time a user answers the form, it will be recorded as a new response. If this option is disabled, each time the same user answers the form, they will be overwriting their previous response.
- Only for registered users: Allows you to determine if the form will only be visible to registered Modyo users. If this option is enabled, an unsigned user will not be able to view the form. If this option is disabled, any user can answer the form.
After a division, you will be able to see the options to modify the redirect after a user answers the form.
Default options: After answering the form, the user is redirected to the home of the site associated with the form.
Custom Re-direct URL: Allows you to enter a URL to which the user will be redirected after completing the form. You can type a full URL (e.g. https://test.modyo.com/home) or a path of the site associated with the form that starts with
/(e.g./home). If you type an address that doesn't start with/,http://, orhttps://, the platform addshttp://to it.Thank you page: Allows you to add a personalized thank you message after a user answers the form, along with a button that will take them to the address in Re-direct Link, which accepts the same values as the Custom Re-direct URL. If you check Enable Auto Redirect, the user is automatically redirected to that address after the seconds set in Re-direction Time, or after 10 seconds if you leave it empty.
Enable segmentation: If the form is private (only registered users can answer it), you can select a set of users who can answer the form using segments. To learn more, go to Segments
Attention
In case of a public form, users who do not have an active session in Modyo, will see three required fields at the top of the form: First Name, Last Name, and Email. If the realm doesn't use the email as the username, they will also see a fourth required field for the username, with the label the realm has configured. While any of these fields is empty or the email is not valid, the submit button stays disabled. Once they submit the form, a user will be created with those values, and then the response will be associated with that user.
Attention
If a user, who doesn't have an active session, completes the form, and their email matches an already registered user in Modyo, the response will be linked to the existing user, and a new user will not be created.
# Edit form
To modify a form, follow these steps:
- In the side menu, select Customers and click Realms.
- Select your realm and click on your form.
- In the options menu at the top right, click "Edit".
Once you enter the editing section of a form, you will be able to see 2 sections: a central section, where you can rearrange the questions by dragging them in the required order, and the right side section, which has three tabs:
# Add
This section will allow you to add as many fields as necessary to complete the form, or delete the ones that are not necessary. The fields are grouped under two headings:
- Content fields: Fields that only show information to the user and do not capture an answer.
- Input fields: Fields that ask the user for a value.
The Content fields group has one option:
- Rich Text: Shows a block of formatted text, such as instructions or a legal notice. See Rich Text.
These are the field types of the Input fields group:
- Simple Text: Allows the user to enter a single line of text. To limit its length, set Min and Max in the field properties. If you don't set a Max, it accepts the same length as the Paragraph Text field.
- Paragraph: Allows the user to enter multiline text up to 65535 characters.
- Number: Allows the user to enter numbers.
- Dropdown: Allows you to add options from which the user can choose one in dropdown format.
- Checkboxes: Allows you to add options from which the user can choose multiple options with checkboxes.
- Choice: Allows you to add options from which the user can choose one in radio button format.
- Date: Allows you to add a date field where the user can select one within the allowed range. See Date.
- Nested questions: Allows you to add a series of alternatives that can be nested, so that the user is asked to select one of the possible nested options within the option they selected.
- File: Allows you to upload files.
- Email: Field for entering an email address.
- URL: Field for entering a web address.
- Country: Country selector.
- Phone: Field for entering phone numbers.
- Address: Structured field for capturing addresses.
- Hidden Field: Stores a value with the answer without showing it to the user. See Hidden Field.
You can delete one of the fields from the form by clicking on the trash can icon to the right of each field in the main section. The deletion will be effective once you save the changes.
Danger
If your form is already activated, and you already have answers, be very careful when deleting questions from it, because by doing so, you will be removing the values from those answers that users have already submitted. This action is irreversible.
# Rich Text
The Rich Text field is a content field: it shows a block of text inside the form and does not generate any answer. Use it for instructions, legal notices, or any informative content you want to place between the fields, including images or files to download.
When you select it, the editing section shows the Field title, the Identifier, and a rich text editor. It has no required option and no instructions. If you fill in the Field title, the form shows it as the heading of the block.
From the editor you can insert images and files from the realm library. The options to upload, edit, or delete files appear according to your permissions on that library.
The content accepts HTML and Liquid, with access to the site variables (vars) and to the signed-in user (user), which is empty in anonymous answers. For example:
<p>Hi {{ user.first_name }}, review the terms before submitting the form.</p>
Keep the following in mind:
- If the Liquid has a syntax error, the field is not saved and the platform shows the error.
- The content of each field accepts up to about 64 KB of HTML.
- The accepted HTML is limited. By default, the allowed tags are
a,abbr,acronym,address,b,big,blockquote,br,caption,cite,code,col,colgroup,dd,del,dfn,div,dl,dt,em,h1toh6,hr,i,img,ins,kbd,li,mark,ol,p,pre,s,samp,small,span,strike,strong,sub,sup,table,tbody,td,tfoot,th,thead,time,tr,tt,u,ul, andvar, and the allowed attributes areabbr,alt,cite,class,colspan,datetime,height,href,lang,name,rel,rowspan,src,style,target,title,width, andxml:lang. - Link and image addresses only accept
http,https,mailto, andtel, or relative paths. If you insert a link with another scheme, the editor shows a warning. - The editor removes what is not allowed. If the content has HTML outside that list when you save it, including when it comes through the API, the field is not saved and the error states what is not accepted, for example
<iframe>,id, orhref="javascript:". - When the form is displayed, the platform filters the content again, including the output of the Liquid: it removes the tags and attributes that are not allowed, keeps their text, and removes
scriptandstylealong with their content. - These rules also apply to the Rich Text of the Input tasks of originations, to the instructions of Add a Field Pop-up instructions in their fields, and to the document of the Signature task.
- It does not appear in the answers: it is not shown in the detail of an answer or in the new answer notification email, it is not included in the export or in the form statistics, and it is not available to filter segments by answers.
- If an answer carries a value for this field, for example through the API, the platform discards it.
# Date
The Date field captures a day, without a time. The answer is stored as 12:00 UTC of the selected date. That's why, if you read the answer through the API or in Liquid, the value carries a time that corresponds to 12:00 UTC, not to midnight. To get the day, take the date part of the value expressed in UTC: if you convert it to another time zone, the date may change. Answers saved before the platform adopted this format were also adjusted to it.
If you send the answer from your own code, use the yyyy-MM-dd format, which is taken as that exact day. A value with a time is converted to the account time zone, and the resulting day is stored.
The Min date and Max date are compared by day, without considering the time.
# Hidden Field
The Hidden Field stores a value with the answer without showing it to the user, such as the source of a campaign or a site value. The value is stored as text and appears like the value of any other field: in the answer detail, in the export, in the notification email, and in the segment filters by answers.
When you select it, choose in Value source where that value comes from:
- Fixed value or Liquid: The platform computes the value when the answer is saved, from what you write in Value, regardless of what the browser sends. It accepts up to 1,000 characters and Liquid with access to the user the answer is linked to (
user.name,user.first_name,user.last_name,user.email, anduser.username), to the form site (site.name,site.uuid, andsite.url), and to the site variables (vars). In forms open to users without a session, the user data depends on what the respondent enters. You can use the standard filters and theassign,capture,case,comment,echo,if,unless, andrawtags, but not loops orinclude. - URL parameter: The value is taken from the parameter set in Parameter name, from the URL of the page where the form opens. For example, with
utm_sourceas the name, a URL ending in?utm_source=newsletterstoresnewsletter. The name must start with a letter or a digit, only accepts letters, digits, dot (.), hyphen (-), and underscore (_), and has a maximum of 100 characters.
For example, this Value stores the user's email:
{{ user.email }}
Keep the following in mind:
- It has no required option and no instructions.
- It is only available in forms. It does not appear in the Input tasks of originations.
- With Fixed value or Liquid, the Value is required, and if its Liquid has a syntax error, the field is not saved and the platform shows the error.
- Up to 255 characters of the value are stored, and the rest is discarded.
- If the value is empty, for example because the URL doesn't carry the parameter or because the Liquid fails when it is computed, the answer doesn't include this field.
- The value is computed again every time the answer is saved. If the user answers a form that doesn't accept multiple answers again, the previous value is not kept: with URL parameter, the field is left empty if the URL no longer carries the parameter.
Attention
The value of a URL parameter comes from the browser, and anyone can change it by editing the URL. Don't use it for sensitive data or for decisions that require a trusted value.
# Field properties
This section will allow you to modify the options for each of the questions on your form, you must select a field from the main section in order to make use of this section.
All input fields have a title, which will be the question associated with the answer, the option to make it a required field in order to submit the form, and a brief description, if instructions are needed, to answer the field. The Hidden Field is the exception: it has no required option and no instructions.
The Dropdown and Nested Questions fields have the Enable search checkbox, unchecked by default, also when their alternatives come from a data set. With the checkbox checked, the user sees a search box instead of the browser list: as they type, it finds the alternatives that contain the text, ignoring case and accents, shows them in the order you defined, and displays up to 100 matches. In nested questions, the search box appears at every level. The same checkbox is available in the Input tasks of originations. The Country field and the country selector of the Address field always show this search box, which also finds each country by its two-letter ISO code.
Some fields have validations, to ensure that the user meets certain requirements to fill in the field, some of these restrictions are:
- Minimum length: Length required for the text to be valid
- Maximum length: maximum length allowed for text to be allowed
- Regular expression: Format of the text entered must match the associated regular expression to be valid.
- Minimum number: The number entered cannot be less than this value.
- Maximum number: The number entered cannot be greater than this value.
- Minimum Date: The date entered cannot be earlier than this value
- Maximum Date: The date entered cannot be later than this value.
Just as some fields have validations, some input fields let you set a default value that is preselected when the form loads: Single Text Line, Paragraph Text, and Number, in Default answer; Date, with the Default checkbox; and Checkboxes and Choice, by checking one of their options. Country, Phone, and Address only let you use the user's current location as the default country, or country code. In the builder, Dropdown, Nested Questions, File, Email, and URL don't let you set a default value. Since Rich Text does not capture an answer, it only has a title, an identifier, and content.
# Regular expressions
For simple text and paragraph fields, you can add validations through regular expressions. On save, the platform checks that the expression is valid according to Ruby regular expression syntax, both in forms and in the Input tasks of originations. If it is not, the changes are not saved and an error shows that the regular expression is not valid. The editor marks in red the expressions the browser can't interpret, but that mark doesn't guarantee that the platform accepts them. Since the answer is validated both in the browser and on the platform, use an expression that the editor doesn't mark in red and that saves without errors.
By clicking on the functions button, you can see the different default validations:
- URL
- Phone Number
- Chilean RUT
- Bank card number
- US zip code
- Canadian zip code
- Chilean zip code
- UUID
Selecting any of the different options and clicking Add will autocomplete the expression to the field.
# Form properties
This section allows you to change the form's general behavior. It is similar to the creation view of a new form, but it adds a couple of new options, as detailed below.
Its sections are:
- General
- Snippet
- Options
- Notifications
- Custom JS
# General
The General section adds two options:
- Submit button text: Allows you to customize the text associated with the Submit button on the form.
- Enabled: Allows you to determine whether or not users will be able to answer the form. If the option is checked, then the form can be accessed and answered, if it is not enabled, then users will not see or be able to respond to it.
# Snippet
The Snippet section, which will only appear if the form is public, will allow you to copy an HTML code that you can use anywhere to dynamically load the form, even outside of Modyo.
Attention
In order to make proper use of the form snippet, you must take into account the CORS configuration of your Modyo account and the security headers where you are inserting the snippet.
To make use of the snippet within a page on the Modyo platform, you must copy the Javascript code inside the Javascript section and the div in the HTML section. The HTML section in Pages cannot run Javascript, the use of the Javascript section is mandatory to run the code correctly.
The Options and Notifications sections don't add anything other than what's found in New Form
Attention
If you're using a Modyo site with a custom domain, you'll need to enable the option to share resource sources CORS in the platform settings.
# Notifications
In the Notifications section you can configure the different emails that are sent after a user answers the form.
The email notification sends an “administrative” email notifying you via that channel that someone has answered the form. You can assign a subject and a list of emails to which you want to notify.
The thank you email allows you to customize an email that will be sent to the user who answered the form. You can customize both the subject and the body of the message using Liquid. Below the field for customizing the message, you can see a list of variables that you can use to personalize the email.
Below is an example of code that you can use as a basis for customizing the thank you email.
Message Sent: {{ 'now' | date: "%b %d, %y" }}
<table width="600px">
<tr>
<td><b>user name</b></td>
<td colspan="2"> {{user.name}}</td>
</tr>
<tr>
<td><b>user first name</b> </td>
<td colspan="2"> {{user.first_name}}</td>
</tr>
<tr>
<td><b>user last name</b></td>
<td colspan="2"> {{user.last_name}}</td>
</tr>
<tr>
<td><b>user email</b></td>
<td colspan="2"> {{user.email}}</td>
</tr>
<tr>
<td><b>form name</b></td>
<td colspan="2"> {{form.name}}</td>
</tr>
<tr>
<td><b>form description</b></td>
<td colspan="2"> {{form.description}}</td>
</tr>
<tr>
<td colspan="3" align="center" background-color="#f0f8ff"><b>Questions</b></td>
</tr>
<tr>
<td width="15%"><b>Question type</b></td>
<td width="15%"><b>Question</b></td>
<td width="70%"><b>Answer</b></td>
</tr>
{% for question in form.questions %}
<tr>
<td>{{ question.type }}</td>
<td>{{ question.title }}</td>
<td>{{ question.answer }}</td>
</tr>
{% endfor %}
</table>
# Custom JS
Add functionality, such as custom validation, to your form using Javascript by following these steps:
- On the Modyo platform, within your realm, click on your form.
- Click on more options and click on View.
- Open the developer tools and inspect the element you want to modify.
- Note the id of the element to be validated. (e.g.
answers_3684_value) - In the Custom JS section you can add validations or extra functionality using Javascript.
- Click Save.
Tip
This script will run after the div containing the form, so it's important to keep in mind that it can be affected by the rest of the site's configuration. For example, if this form is embedded in another external site that cannot run Javascript.
# Answers
When you click on a form, you will arrive at a view where all the answers that users have submitted and the date they responded are listed.
You can export the responses to a XLS or CSV file by selecting them from the list and then using the bulk actions at the bottom of the list.
Danger
You can delete answers, one by one, using the action to the right of each answer, or by making use of mass actions, selecting multiple answers and then the Delete button at the bottom of the list. Keep in mind that this action is irreversible and once a response has been deleted, it cannot be recovered.
To see a user's answer in detail, just click on the user's name, and you'll access the list of questions along with the answers that user sent on that particular occasion.
← Segments Origination →