What is the form component?
The Form Component is a Data Component that you can add to pages within your app for users to add and edit records from the live app. Form components can also be used to automate workflows by triggering custom-automated tasks when forms are submitted, and they can also be used to automatically add and update records behind the scenes.
How forms are processed
Once you add a form to a page, each form goes through a process starting from when the form loads onto the page on the live app until after the form is submitted.
While each form's trajectory occurs within one process, we have broken down this process into multiple steps in order to visually explain this process as clearly as possible.
Fields populates within the form
Display Rules are processed in real time
Button Display Rules run
Form is submitted:
Validation rules are run
Post submit- Validation Passed:
Record Rules are run
Emails are sent
Text messages are sent
Submit rules are run
Let’s explore each of these steps involved in the form component's process. go through what each item means then give more details on about each of these steps.
1.1. The form loads onto the page on the live app and the fields populate within the form.
1.2. Any Display Rules are triggered and dynamically applied based on the form values. Display Rules are custom-defined rules to show or hide fields based on other fields within the form. For instance, you could have a Display Rule stipulating that if the “Status” field is set to “Other” within the form ,show a text field that says: “Please elaborate.”
2.1. The form is then submitted, but before any data is added or updated within the database, any Validation Rules are run. Validation Rules enable you to check if the values entered within the fields are correct. For instance, you could have a validation rule stipulating that if the uploaded file is not a PDF file, show a custom error message.
3.1. Post form submit, Record Rules are run. Record Rules enable you to automatically insert new or update existing records once the form has been submitted. For instance, you could remove the "Created At" field from the form and create a record rule stipulating that the "Created At" field be automatically set to the "Current Date and Time" of when the form is submitted. You can use record rules to automatically update and add new records behind the scenes each time a form is submitted.
3.2. Any automated emails that you designated within the form settings are now sent.
3.3. Any automated SMS/text messages that you designated within the form settings are now sent.
3.4. Any Submit Rules that you created within the form settings are run. Submit Rules are the last item to run within the process of a form and they determine what users should see next after they have submitted the form as well as where the users should be routed after they have submitted the form. For instance, you could create a submit rule stipulating that if the "Job Status" is set to "Completed" within the form, the user should be routed back to the home page once the form is submitted. You could create another submit rule stipulating that if the "Job Status" is set to "Incomplete" within a form, route the user to the details page of this job.
Adding form components
Forms can be added to a page for a variety of functions, and some form functions can only work when the form is added to a specific type of page. Therefore, before adding a form component to a page, it is important to plan ahead for what you want that form to accomplish, and based on the form's intended function you will know within which page you should add the form.
For instance, if you are adding a form component to add new records, this form can be added within any page in your app. However, if you are adding a form component to edit records, this form can only be added to a child page, such as a details page.
If you are adding a form component to add connected records, meaning to add records that are connected to the current page's records, this form can only be added within a details page of a connected data table. For instance, say you have a Companies data table and an Employees data table and each employee works for a specific company. Within the Companies details page, you can add a form to add new employees, which will add new employees and connect each one to the company that they work for.
By thinking ahead about what you want each form to accomplish, you will be able to easily determine on which page you should add the form.
Like all other data components, form components can be added to a page within your app, specifically within a column on the page. To add a form component, click on the blue + icon within the column you wish to add the form component to and select the form component from the drop-down list of components.
Once you click on the form component to add it to the page, you will be prompted to select the data table for which you want this form to add and edit records. You will also be prompted to configure the form component using either the Quick Add or Customize option.
If you choose to configure the form using Quick Add, all the fields within the data table that you selected for this form will automatically be added to the form within a two-column layout. If you select the Customize option, you will be able to manually customize the form layout as well as manually select which fields you would like to add to the form.
To learn more about adding data components, selecting data tables, and configuring component settings with either Quick Add or Customize, please see the Data Component Overview article.
If you added the form component using the Quick Add option, all fields within the selected data table have been automatically added to the form within a two-column layout and the form is now ready for use or further customization if you wish.
However, if you added the form component using the Customize option, you will be directed inside the form component where can manually create the form layout and select the fields that you wish to add to the form
Structuring the form layout is similar to structuring pages. You can add rows and columns and specify how many columns should appear within each row. You can then add fields within the columns of your form layout to add those fields to the form.
For instance, the image below shows a combination of a one-column and two-column form layout:
On the live app, this form component will display as follows.
By default, each new form that has not yet been configured comes with a default row with one column. You can either add your first field within the default column by clicking on the blue + icon within that column and selecting the field you wish to add from the drop-down list of fields:
Or, you can restructure the row into the number of columns of your choice and then add fields within each column:
You can also add fields to columns within your form by selecting them from the list of fields on the left-side menu under the Fields tab. Clicking on a field within this field list will add the field to a column on the form.
Once fields are added you can further customize the field options which will vary depending on each type of field. All fields will have options to customize the display of the label position and style or hide it entirely. To edit the field options hover over the field and click the Edit pencil icon.
Customizing form fields
When editing a field you’ll come across certain fields that have some unique options. Here we’ll go over the standard options as well as extra settings available in some field types. Connection fields have many unique options and that is covered in the next section.
Any basic field can be set to be:
This will ensure that the form is not submitted unless this field is not blank.
At times you might want to hide the values being entered for data privacy concerns, you can do this by setting the value to password. Keep in mind, this is not intended for storing password since the values entered while they are encrypted on the database, they are not “hashed and salted.” This is only intended for instances when a user enters something like a social security number, this can add an extra level of security.
Enabling this will disable the form field so it can not be edited. This is disabled in the browser, not server-side making it less secure. For added security, don’t add fields into forms you that are sensitive and should be allowed to be changed. You should add it as an HTML variable or details component. Learn more about that in our security sections.
In some instances you can change the required or read only option dynamically using Display Rules which is covered further down.
The label is the part of the field that displays the form title. For example, in the picture below “Job title” is the label.
You can choose to customize the label to nearly any configuration you see fit including custom label position:
When positioning the label to the right or left, you can choose the size relative to the full 12 columns. For example, 4 columns would make the label 4 columns and the field 8. (4 + 8 = 12).
Aside from the position, you can add custom icons and customize the style of the label. As you can see here, we made the label on the left, with a larger blue font and a calendar icon.
Let’s look at some custom options available for certain field types.
When using a radio field you can customize each radio option’s display to either be inline or new line for each option.
The option text can also be customized to be hidden, top, right bottom or left.
If you chose to use icons in the data builder when using this field, you can make the icons the selectable instead of the little circle radio button.
In the data builder each option is assigned an icon as can be seen here:
To use the icons as the options in the form, choose Yes next to Show Icons:
The size and positioning can be customize as well anywhere from 1X to 10X
The options displayed will be sorted the way they were added or are sorted in the data builder. However, you can override that setting by changing Sort Alphabetically option in the field options of the form.
Rich Text / Long Text
You can set the default height for these fields to any pixel height you need.
With the address field you can add a button that will auto populate the address field to the current user’s location.
Date range field
With date range field, you can choose to only show only all All Day events, essentially hiding the time select dropdown.
Customizing connected fields
Connected fields are fields that are connected from fields within the form's data table to another data table. You can add Connected Fields to a form to enable users to view those connected values within the form.
For instance, if you have a Course Registration App with a Course Catalog page, you can add connected fields to the course form to enable users to view connected values such as the course capacity for each course.
Filter by records logged in user is connected to
There are 2 ways a user can be connected to a record.
- From the users table to another table. For example, each User can be assigned to a specific company in the Companies table. (From User to Company. Meaning, the connection field is in the Users table)
- Each company is assigned to a logged in user. For example: from the Companies table you chose who is in charge of this company. (From Companies to Users. Meaning, the connection field is in the Companies table)
For option 1 when the connection is from the Users table to the second table, you can add a filter to only show records that this is user is connected to. For the next option, please see below how to filter connected records.
Let's look at an example: we have 3 tables.
- Jobs (Each job is assigned to a company)
- Users (Each user belongs to one or more companies)
In this scenario, each User (logged in) belongs to one or more companies. When a logged in user adds or edits a job we want him to only assign the the Job to companies he's assigned to. We can accomplish this by adding the Limit filter in the field.
Be enabling this option, only Companies that this user who is logged in is connected to will appear as a drop-down option.
Filtering connected options.
With connection fields by default all values will be displayed as an option. For example, if we have Companies and Jobs tables and we would like to add a new job. When adding a new job we have a drop-down to choose which company this job belongs to. We can filter out the options to only show companies that meet specific criteria. In our scenario, we only want to see companies that were created by the logged in user. We would do this in the Filter tab of the field options add a new filter as follows:
Add new option
You can also enable an option that will create a sub-form where you can add additional options at the same time.When this is enabled and saved a new child page will be added with a form that can be customized just like any other form.
If you want to filter a drop-down based on a value from another connected fields
Our use case: We want to track all of our customers' cars, including the car make (Ford, Audi, BMW, etc.) and the car model (M5, TT, F150, etc.). Instead of using text fields, we'll use drop-down fields so our users can select the make and model from the drop-down list.
The Problem: If our user adds a BMW there's no need for them to see the car models belonging to the Audi or Ferrari.
The Solution: Using Dependent Drop-Downs
To do this, let's first go over our data structure. Since different car models connect to one car make, the parent item is the Car Makes data table and the child item would be the Car Models.
Here's how our data is structured in the builder.
Car Makes Data Table:
Car Models Data Table:
We have 2 fields- one is Car Model and the second is a connection to the Car Make. This will allow us to select one Car Make for each Model we add.
My Cars Data Table:
This is where we'll be adding our cars. We'll need to select a car make, then a car model. So we have 2 connections- one to Car Make and the second to Car Model,plus any other fields you require.
Now that we know how the data is structured, let's take a look at setting the dependent drop-downs.
Let's open or add a new My Cars form.
Find the field (Car Model) that we want to ensure only shows values based on a parent item (Car Make), and click the pencil icon to edit.
Under the General tab in the last option for Show choose:
Car Models connected to this form's Car Makes
When users now select the Model, only records which are related to the Make will appear in the list.
Adding related records while filtering by connected records.
When inside a details page of a record, you have the option to add a form component to insert a new related record while filtering from only records connected to the details page.
For instance, say you have three data tables:
- Companies data table
- Locations data table with a connection field to Companies (each location belongs to a company)
- Events data table with a connection field to Locations (each event belongs to a location)
As you can see in the image above, the Events data table is related to the Companies data table via the Locations data table but it is not connected to the Companies data table.
Now, say that when you are viewing the details of a particular company you would like to add a new event and when choosing the event location, you would like to only see locations connected to this particular company within the location drop-down list.
Let's walk through how we can accomplish this.
Below is an image of this example's Locations and the Companies each location is connected to.
Say we are inside the details page of the company, Tadabase. Within the Tadabase company's details page, we will add a form component to insert a new event as well as select a location that is connected to Tadabase. Within the location field's settings on the form, we'll edit the Show settings to only show locations connected to this page's Company.
Now, when we add a new event via the form on the Tadabase company's details page and select a location, only locations connected to Tadabase will show.
Viewing connected values
When we have a connection field inside a form we can choose to view (read-only) any values from that connected record inside the form.
Let’s look at an example:
We have our typical Jobs and Companies table structure. Each job belongs to a specific company. Therefore, when we add a new job we’ll have an option to select the company this job will belong to.
In our scenario, we want to see the current status of this customer inside the form. As you can see we can view the Status change depending on which customer we choose. This is display purposes only. If you want to restrict form submissions based on the connected values, see the Button Rules section when you can disable the form if Status is not equal to Active.
If you have more than one connection field in the form, you’ll see a small drop-down icon under the Connected Fields section.
When the form is adding a new record, the connection field must be present. However, if the connection has already been made and you’re editing the records, the connected values will be visible.
At this time if you this is a connection of one-to-many only the first result will be displayed.
Field Display Rules
Show and hide fields based on rules and other values.
You can add as many groups of conditions and each group can have it’s own custom actions. Within each condition you can choose if it should require all the conditions be met to run the display rules or any conditions must be met. (Or).
Using display rules you can choose to use any combination of these actions when a display rule is met:
When the display rules are met, show another field in the form.
When the display rules are met, hide another field in the form.
Rename field label
When the display rules are met, rename the label field of another field
Require a field
When the display rules are met, make a different field required
Do not require a field
When the display rules are met, make a required field not required
Enable a field
When the display rules are met, enable a disabled field
Disable a field
When the display rules are met, disable an enabled field
Note: be sure to not create impossible conditions. For example: Require a field and make it disabled at the same time. This will make the form impossible to submit.
Display rules are run in order from top to bottom. If one rule matches more than one condition, the last rule to be triggered will win.
Button Display Rules
The following options are available in button display rules.
Set text color
Set text style
Set background color
Hide text value
With validation rules you can ensure that certain restrictions are applied prior to form being submitted. For example, if date field is in the past, display an error.
You can run validation against custom values or other fields values.
You can add as many validation rules as you wish, each group of rules will be combined into “AND” not “OR”
Custom value validation is something like this:
If Created At is more than 14 days ago show an error.
You can also validate against the value from another field. For example: If “End Date” is before “Start Date” show an error. Here’s how this will look in the builder:
On the front end, the error message will appears like this:
From the screenshot above you can see we wrote a custom error message to be displayed. Aside from basic messages, this message can be customized with field values as placeholders. For example, we can show an error and customize the text based on field values:
Validation Rules on Connection fields
When adding validation rules on a Connection field that is One to Many you can choose to validate if one or any value is unique. For example, If in the database we have the following events:
As you can see each even is assigned to one or more (one to many) locations.
When adding a new event we want to validate to make sure the location is unique.
By adding this condition to check if All values are not unique:
If we choose a value that is not unique we will get an error:
However, if we choose at least one value that is unique in that record, the form will submit successfully:
As you can see above, even though "Ballroom" and "Main Hall" are not unique, "Executive Lounge" is unique and will therefore work.
Choose "Any value is not unique" will have the opposite affect. If any of the values chosen are not unique it will fail the validation test and the form will not submit.
Adding Validation Rules
To create validation rules, start by adding or opening any form in your pages
Next select Form Rules then select Validation Rules and press the Add New Rule button to create your first rule
We'll add a rule like in our example - if Created Date is in the past show an error message. To do this we'll select the Created Date field and choose the is before today option from the drop-down. If this equals to true the error message will be displayed
Users will see an error that looks like this:
When creating action links and record rules you’ll have many options as to what should run and when.
Update this record
Update connected record
Insert connected record
Insert New record.
Once you decide what you want to update, you can choose the value to be used for making the update.
Set to blank
Logged in user field value
Auto Logged User (when the field being set in a connection to the User’s table)
Current date/time (when the field being set is a date or time field.)
This will be any static value you wish to use. The options will be dependent on the type of field. For example,
- Date/time field’s custom value can only be a date and time.
- Text field can be any value.
- Connection field must be a predefined connected record.
- Option fields can be any option from the list of options in that field.
Set to blank
This will NULL the value
Use any other field or value from your record to set this value for.
Retrieve the value from a record this is connected to and use that value.
Logged in user field value
Get any value from the Users table for the logged in user and use that value.
Auto logged user
If the field being updated is a connection field to the Users table, you can set this value to be auto saved to whoever is logged in.
Current date and time
When working with date and time fields this will save the date and/or time to the date and time this record was submitted.
When working with current date and time, the timezone in your app will be used for this date/time value. Be sure the timezone in your app is set correctly. Click here to learn more about setting your timezone.
Customers and Jobs.
Each Job connects with one customer, but each customer will have many jobs.
With form record rules, you can automate record values as well as create or update additional records after forms are submitted.
For example, instead of having a date field inside the form, you can remove the date field and set the value of the date to the current date automatically.
In this help article we'll cover:
Updating Current Records
Updating Connected Records
Inserting New Connected Records
Inserting New Non-Connected Records
To get started with any of these record rules, open or add any form:
Select Form Rules, then Record Rules, and then Add New Rule:
Updating this current record
Condition: Add any conditions for when this rule should take effect. You can add as many rules and as many conditions as you need. A sample rule: If Date is more than 90 days ago, set status to Archived
Tip: A simple way to view and understand the rules is to simply read the entire section as a sentence.
Update this record when date is before 90 days and set the Status to a custom value of Archived.
You can add more than one value to be set in a single record rule. For example: Update this record when date is before 90 days and set the Status to a custom value of Archived and set Date Created to today’s date.
On that same note you can also add multiple conditions of when this record rule should be triggered.
For example, only when date is older than 90 days, but before 180 days.
Value: Set the values to be updated and choose the value either based on a static value or based on one of the following:
Custom Value - Choose a static value that will be used every time this condition is met.
Set Blank - This will null the value.
Form Value - Use the value from another field in the form to update this particular field's value.
Connected Value - If this table has a connection to a parent table, get a value from the parent table and use that to update this field's value. For example, if you're adding a task which belongs to a project, you can get the value from the project table and update the task based on the connection.
Logged in User's Field - Use any field which belongs to the user who is currently logged in and is adding/editing this form. For example, to add the license number of the logged-in technician, you can retrieve the value of the logged-in technician and save it to this form as a static value.
In this first example, we'll simply update the field to the current date
Every-time this form is submitted, even if the field is present in the form it will be overridden by the record rule.
Update Connected Record
For this example, we must first describe the scene. We have a list of projects and each project has multiple tasks associated with it. Similar to the following structure
The connection relationship will look along these lines: Projects
Project Tasks - each Project Task is connected to a single project. Meaning, when we add a new Project Tasks we will have a dropdown to see all the projects. (this can be automated too see this section for more details).
Our objective here is:
Whenever we add a new task and assign this task to a specific project we want to update the Project record and set the “Last Task Added” field to the current date and time. This way we can glance and see some task activity from the Projects table.
To begin let's open the add form where you'll be adding additional tasks to a project.
choose Update Connected Records
Select Projects from the dropdown.
Under Value choose Last Task Added
and select Current Date & Time
When new records are added the Last Task Added in the parent Projects table will be updated to the current date and time.
Update this record and get value from connection.
Objective: In this example we’ll assume the same structure:
Project Tasks - each Project Task is connected to a single project.
When adding a new project task, we will assign this task to specific project, however, we want to save the “Task Due Date” to the value of the “Due Date from the Projects table.
Once a form has gone through the process of being validated using the Form Validation Rules and has been added you can choose from one of 2 options.
Show confirmation message
Redirect to an existing page
Redirect to another website URL
To get started with Submit Rules open or add any form onto the page
Select Form Rules then choose Submit Rules
Show Confirmation Message
All rules are applied in order and a default rule exists for all submissions which don't have a unique rule assigned to them. For example, you can customize the message based on specific criteria, for example, if Priority field is Highest
Press Add New Rule
Choose Show confirmation message under the Action
Add new condition, for example, if Priority is Highest
Enter the message to be displayed if this equals true
When users submit this form where Priority is Highest the custom message from above will appear.
Redirect to an Existing Page
Just like Confirmation Message rules you can have multiple rules with conditions. For example, you can customize the redirect based on specific criteria, for example, if the Priority field is Highest then route to a specific page.
Press Add New Rule
Choose Redirect to an existing page under the Action
Add new condition, for example, if Priority is Highest
Select the page for user to be redirected to
In the above image, you can see we have two rules.
The default rule will simply show a message saying: "Project has been added successfully. "
If and only if Priority is Highest then the user will be rerouted to the Projects page
Redirect to Another Website URL
Just like the above rules you can have multiple rules with conditions. For example, you can customize the redirect based on specific criteria, for example, if the Priority field is Highest then route to specific URL. You can even include parameters in your redirect such as POST and GET parameters. To learn more about how to use this, check out the article on Adding PayPal Integration which utilizes redirect with parameters.
Press Add New Rule
Choose Redirect to an existing page under the Action
Add new condition, for example, if Priority is Highest
Add the URL for the user to be redirected to
If you'd like to include parameters and values from the form in the redirect using GET or POST methods, select Yes by Send Query Parameters and choose the Method of GET or POST
(Details on how this works is beyond the scope of this tutorial, but know that if you have a service that can consume GET or POST requests you can push data directly from the form to those services. Check out requestcatcher.com to test your integration
You can have one or multiple unique emails sent out, each with their own conditions. For example, if Priority field is Highest then send a unique email to Manager.
There are two types of emails which can be utilized:
Basic Emails - All the fields in the form are sent to a custom email address if no conditions are set or if a condition is met
Custom Emails - Choose many options such as who the email should be sent to, which fields should be sent, the subject, the email text, and more.
In Type choose Basic Email
Condition - Add any conditions where this email should be sent.
Send - enter email address where record details should be sent
When form is submitted, an email will be automatically sent to firstname.lastname@example.org
Custom emails can be highly customized to match very particular requirements.
You can add one or multiple recipients who should receive this email.
The recipient can be or any combination of the following:
Logged in User’s value.
Custom value is essentially using one name/email for all emails.
Filed Value is able to dynamically retrieve any email address field you have in the current form or connected form.
As an example: If we’re adding a job and this job belongs to a particular customer. When adding the job we can choose to email the email address in the customers table for the customer that this job will belong to.
Logged in user’s field.
This can be useful to set the From name and from email to the name and email of the logged in user.
dynamic name and email address or static. Dynamic values comes from the database/logged in user. Static values or a value you save in the form settings and the same details will be used each time.
Types of dynamic values:
In Type choose Custom Email
Condition - Add any conditions where this email should be sent.
Send - Choose who should receive this email. You can choose multiple people and if they should each be in the TO field, CC or BCC field. You can also choose to send an email to an email address of either this record or a connected record. To use the Field option, an email field must be present and not blank in the current form.
From Name - Name that should appear for who sent this email.
From Email - Email address that should appear for who sent this email
Subject - add a custom subject or even customize the subject with values from the current form values by clicking Add Field
Message - Write a custom email message and add which fields from the form to include in the email.
When a new record is added with Priority of Highest a custom email will be sent