Overview

The most common form widget is the Single Field widget. This allows you to enter the value for a single field, with slightly different controls based on that field’s data type.

You can change the field used by the widget in the widget’s Edit dialog.

State

Most of the time you’ll want single value widgets to be Editable. If we just want to show the value of the field for reference, however, you can change a single value widget’s state to Text Only.

This is what a Text Only single value widget looks like when you’re using a form.

When the widget's state is Hidden it disappears from the form entirely. When it's Disabled it looks the same as Editable except it's grayed out and its value can't be changed.

A widget's state, like many other of its properties, be changed with form actions so you can hide and show, or enable and disable widgets as users are filling out a form.

Type: Single-line or Multi-line

Single value widgets will often be Single-Line, but you can also change their Type to Multi-Line.

This allows forms to collect paragraph-stye text.

Values to show in Dropdown

One of the most useful features of forms is the ability to make data entry easier. The default option for “Values to Show in Dropdown” is None.

This allows the form’s users to type any value they want into a field that looks like this.

If we choose “Other Record Values”, the “Allow Typing New Values” is checked by default.

This allows users to type in any value as before, but it also suggests existing values in the dataset that match what they’ve typed. This can save a lot of time during data entry.

We can also uncheck “Allow Typing New Values” when showing “Other Record Values”. Users will then see a simple dropdown list of options they can choose.

When you choose to show “Specific Values”, the person building the form chooses ahead of time what values will appear. Here we’ve entered three specific companies that users can choose from, and “Allow Typing New Values” is unchecked.

The form will show our three companies in a dropdown list.

You can also check “Allow Typing New Values” when showing “Specific Values”. This will suggest the three companies in a dropdown list, but also allow users to type in something else.

Specific value labels are helpful for showing text labels on the forms that correspond to underlying numerical values.

This allows people to choose one value in a dropdown while another value is saved in the dataset.

Input Validation

Another important feature of forms single value widgets is input validation. By default, input is optional. You can also set validation to Input is Required. This means users will have to enter some value for the field.

Required fields show a blue star beside their label, so people know what they need to fill in before they try to save. A field gets a star whenever its input validation won't accept a blank value, such as “Input is Required” or a “Minimum Length”. If a form action changes a field's input validation while someone is using the form, the star appears or disappears to match.

You can set a minimum length of content. Here we’re saying users must type at least 5 characters.

You can set a maximum length. Here we’re saying users must type 20 or fewer characters.

You can also set both minimum and maximum lengths.

Finally, you can choose custom form validation and enter a regular expression. In this example we’re requiring the input to match any email address from the domains yahoo.com, hotmail.com, and gmail.com.

If you're looking to validate email in general, this is a great one to use.

(?:\W|^)[\w.+-]+@[\w-]+\.[\w.-]+(?:\W|$)

If you're looking to match specific domains, this example only accepts emails from Yahoo, Hotmail, or Gmail, and you can modify it to match any domain of your choosing.

(?:\W|^)[\w.+-]{1,64}@(yahoo|hotmail|gmail)\.com(?:\W|$)

This regular expression is for US social security numbers that accepts either a format of 123-45-6789 or 123456789.

^(?:\d{3}-\d{2}-\d{4}|\d{9})$ 

There are resources across the web to help you learn how to make a regular expression to match the text you want. We’ve found that ChatGPT is amazing at building the perfect regular expression. There are also online tools like RegExr that are really handy.

A widget's input validation, like many other of its properties, be changed with form actions so you can, for example, make a field required or optional as users are filling out a form.

Value change actions

You can choose to run one or more of the following actions whenever a user enters something new in a single field widget:

• Save the current record
• Clear fields and start a new record
• Go to a form page
• Change widget state
• Change widget input validation

You can even develop complex AND/OR and IF/ELSE logic to do different actions based on the form's data or what the form user does as they're filling out the form.

This allows you to build forms that change and update as users interact with them.

Linked fields

Single value widgets can behave a little differently when you choose a field from a linked dataset. In this example we’re creating a single value widget for the “Customer” field in the linked Device Sales dataset.

When your form is on the “many” side of a one-to-many linking relationship, you can choose a single value like any other form fields. When your form is on the “one” side of the one-to-many linking relationship, you can choose multiple values from the linked dataset like in the example below.

You can even use single value widgets for datasets in many-to-many linking relationships that involve a third dataset for linking the other two.

For example, let’s say you have an Employees dataset and a Departments dataset. If you want your employees to be able to be in multiple departments, you’d set up an “Employee Departments” dataset with a field linking to the Employees dataset and a field linking to the Department dataset. You could then choose multiple departments in employee forms, and you could choose multiple employees in department forms.

Suggestion Filters

A Single Field widget that suggests values from other records, or offers records from a linked dataset, normally offers everything the person is allowed to see. Suggestion filters narrow that list, so the widget offers only values from records that match. For example, a Sales Employee field can offer only employees whose Employment Status is Active.

The “Suggestion Filters” panel appears in the widget's settings in two cases: when the widget shows a linked field, and when it shows a single-line text or number field with “Values To Show In Dropdown” set to “Other Record Values”. Click “Add” in the panel to add a filter, just like the filters on a Record List widget. The panel isn't available for many-to-many links made with a linking dataset that has only the two link fields, like the Employee Departments example above.

Filters only narrow what people see. They never show anyone a record they don't already have permission to view. When “Allow Typing New Values” is checked, people can still type a value that isn't suggested.

A filter's value can also come from one of the form's variables. When you add or edit a filter, click “Add Equation” and choose a variable. The suggestions then follow the person's earlier choices. Once they pick a site, for example, an audit question can offer only the open cases at that site, and the list updates if they pick a different site.

To filter by a value from the record being edited, first copy that value into a form variable, for example with a “Set a value” action in the page's “Page Display Actions”. Then use the variable in the filter. A field in the filter's equation won't work for this, because it refers to that field on each suggested record, not on the record being edited.

Showing Part of a List of Linked Records

When a Single Field widget shows the records that link to the current record (the “one” side of a one-to-many link), its suggestion filters also decide which of those linked records the widget shows. For example, an audit response can have many pieces of evidence, each of which records the audit question it belongs to. You can put an evidence widget beside each question and filter each one to its own question. Each widget then shows only the evidence for its question. Removing a record in one widget doesn't affect the others.

When someone clicks “New” in one of these widgets, the new record starts with the values its filters call for. A filter that sets a field to exactly one value, such as Question is “Q4”, fills in that field before the dialog opens, so evidence added under a question is filed under that question. Filters that allow several values, ranges, or exclusions aren't copied to new records.

This only applies to widgets that show the records linking to the current one. On a widget that picks a single linked record, suggestion filters only narrow the choices.

Linking Records Through a Connecting Dataset

Some links need details of their own. For example, an audit response can cite several cases, and each citation needs to record which audit question the case was cited under. That takes a connecting dataset, such as a Case Links dataset with a link to the response, a link to the case, and a Question field.

A Single Field widget can work through a connecting dataset directly. Add a Single Field widget, choose the Case Links dataset and its field that links to the response, and add suggestion filters that set each of the other Case Links fields to a single value, such as Question is “Q4”. The widget then offers existing cases instead of Case Links records, and its “Value Label Field” lists case fields. Each case someone picks creates a Case Links record with the question already filled in when the response is saved. Removing a case removes only that link, and the case itself is never deleted. Nobody types a case ID, so nobody can mistype one.

The widget works this way automatically when all of these are true:

• The connecting dataset has exactly two link fields. One links to the form's dataset, and the other links to a different dataset, such as Cases.
• The connecting dataset has no file fields.
• The widget's suggestion filters set every other field in the connecting dataset to exactly one value, either a typed value or a single form variable. Those fields must be text, number, date, time, or Yes/No fields. Calculated fields and the record ID field don't need filters.
• Any dialogs chosen in “Create New Linked Records in a Dialog” and “Edit Linked Records in a Dialog” are on the other dataset, such as Cases.
• If the connecting dataset has a “User ID Field” permission, it has only one, and the form's dataset also has exactly one. That field doesn't need a filter. Each new connecting record gets the same owner as the record on the form.

The usual linked-record settings still apply. “Allow Linking to Existing Records” must be checked for people to pick existing cases. People also need permission to add and modify records in the connecting dataset, and the connecting dataset must allow manually adding new records.