Components
/
Form

Form

Submit a form to perform actions with input data. The form component provides a way for users to view and manipulate multiple data fields with their inputs, and are a key part of many tools. Upon submission, forms perform functions like creating (inserting) a new data record, updating an existing record or calling APIs.

Ways to use a form

Many inputs from user

Use a form if you expect the user to interact with multiple data fields for the form's function. If you need a user to enter in an email and customer name, select an item from a dropdown, and then write a paragraph of text, forms are your best option. This is usually the best component when your function is to create entirely new data records.

Example:
You’re looking to build a tool to allow your business take new orders over the phone. The tool will need to record the customer name, phone number, address, product SKU, and payment information, and store it in your Orders table in your MySQL database.

Because there are multiple fields with user input, you choose to use a form. For fields like the name and address, you allow the user to type in text. For the Product SKU and Payment Type, you set up a dropdown selector ("Visa", "Mastercard", etc). When submitted, the form inserts a new Orders record with this data into your database.

Verify inputs before submission

Sometimes you may have a process where a user needs to view data fields and confirm that it's correct, or make adjustments if needed. Since form fields can display pre-filled data, you can have every field populated with data, allowing the user to view change any values that they need to.

Example:
Let’s say you have a table of incoming Orders for your business. Before sending these Orders over to be processed, you want a user to review and sanity-check the data in the Order, like the Quantity and AmountPaid.

You can create a form that displays the Orders data, prefilling each field (like Quantity) with the current value in an editable text box. Users can quickly scan the form to review and hit a "Confirm" button to confirm the order or fix any errors they notice before confirming.

We’ll cover a step-by-step example of binding to pre-existing values below.

Want the benefits of a form but without sacrificing real estate in your design? Try a Pop-up Form.

Configuring your form

Actions

First, select the function that this form should perform when it is submitted.

For most databases, you'll see auto-generated insert, update, and delete functions. For example, if you selected your PostgreSQL database with a Users table, you'll see "insert Users record", "update Users record", and "delete Users record" functions appear.

Tip: If you do not see auto-generated functions, check to see if the database credentials used to connect has permission to insert, update, and delete.

For most business apps, auto-generated functions will appear, based on the available APIs of that app. For an app like Stripe, you'll see functions for "insert Balance Transactions record", "update Balance Transactions record", "delete Balance Transactions record", and so forth for the resources available in Stripe's API.

If you created any custom functions for a database or HTTP service, those will also be available for you to choose from.

After submitting options

Usually, if your form submission changes some data that is displayed in the Space, you'll want to update what's displayed. After Submitting options allow you to refresh the data of a component in the Space.

Example:
If you had a form that would update the address, state, and zip code of a customer in the Customers resource, and you had a Customers table displaying those fields in your Space, you should set the Customers table to refresh after submitting, otherwise you will not see the updated address information in the table.


You can uncheck Reset form input values after submitting if you don't want to clear values when the form is submitted. Note that if you have pre-filled default values (coming from another component, generated UUID, etc), those values do not clear (simply reset) even if this is checked.


Fields (and values)

Here you'll determine the actual values that are passed along when the form is submitted. To do this, you’ll select fields, and then specify what values go in them.

Select fields

By default, only required fields are added. For example, If you’re updating a record in a database, this would just be the primary key. Click “Add data” to view a list of all available fields for your selected function.

Specify values

You’ll need to choose a value that is passed in for each field. You can let the user type in a value, get this value from an existing component, set a custom default value, set a UUID, set to null, or set to the date-time the form is submitted (date/time fields only).

Example

Let's walk through a commonly used setup where we get the form values from a table component. In this case, we want to build a form that will update an Orders record. To make it easier to use, we also want to pre-fill the form fields with existing data.

The best way to set this up is to first add a table with your Orders data, which will then provide data to your form.

Setup Tip: While a table & form combination is the most commonly used, you can also use a card list or detail view component to provide form data.

Then, add a form component to your space, with "Update Orders record" as its function. Go to the "Fields" and add all the form fields you want the user to see and update. Edit each field, specifying that the value comes from that same field in the Orders table.

Then save and publish your space. You'll see that clicking on a row in the Orders table will prefill those values in the Update Order form (these two components are now "bound" together).

Check out Field Configuration to learn about all the options for specifying values.

Hidden Fields

Forms are great when you want users to view and potentially edit data fields. However, there are certain data fields where it is unnecessary for a user to view or alter before submitting. For these, you can use a hidden field, where data is still submitted but the field isn't shown to users of your form.

Field Configuration is the same for hidden fields with one exception: a value must be specified, as users will not be able to enter in values (similar to a button).

Tip: Fields like "Created At" / "Modified At" are perfect candidates for hidden fields, since you don't want users to alter this information but you still need it to be passed along. Use the "Set to date/time this form is submitted" option.

If you have a field that's a generated UUID or prefilled with a fixed value, these are also good candidates for a hidden field.