Custom Form

Build custom forms with conditional logic to trigger emails or update data in a variety of integrated systems.

The Form Builder action has been designed to serve a vast array of potential use cases, from customer-facing forms to internal tools.

This article has recently been moved This article is about the Custom Form action (previously the 'Form Builder' for Tessitura). The action was amended to make it integration-agnostic, so that the same functionality could be used with a variety of different integrated systems.

Form settings

Following best practice, where relevant Action Links forms can be split into steps.

Field	Details
Tab style	When you include more than one 'step' in your form, the interface will display a progress bar at the top of your form to show the user how many steps there are and their current position. There are two possible styles for this progress bar – 'progress' and 'tabs'. The 'progress' style displays like a timeline of markers, whereas the 'tabs' style displays as a series of tab buttons.
Hide labels on the progress bar	The 'progress' style will display a title label next to each step's marker on the timeline, checking this box will hide these labels.

Field types

Action Links provides a range of field types for you to use in your forms. Although many field types appear visually the same (e.g. text, number, email), it's important to use the correct type so as to aid assistive technologies to effectively identify a field's role.

Field type	Details
Text	An input field with type 'text'.
Number	An input field with type 'number'. Most browsers will apply validation to this field type to prevent non-numeric characters from being entered or submitted.
Email	An input field with type 'email'. Most browsers will apply validation to this field type to prevent the form being submitted if the given value doesn't follow the pattern of an email address.
Date	A date input field. Most browsers will display a date select tool with this field type, enabling the user to more easily select a date.
Password	An input with type 'password'. Most browsers will obscure the value of this field as it is input using • symbols.
Barcode	An input field with a scan button that will launch the device's camera. Supports a range of 1D (product/industry) and 2D barcode types, including QR codes. When scanned, the field will be populated with the barcode string.
Textarea	A textarea field, giving a user additional space for their response. You can also specify a number of rows to display (default is 3), although the user is able to expand the field themselves.
Dropdown	A select field. Specify a series of dropdown options, including a label (that will be displayed to the user) and value (that will be passed in the form submission) for each. The label and value can be the same, or different.
Autocomplete (Algolia)	See Algolia – Autocomplete in forms.
Read only	A read only field. This will be displayed to the user and passed in the form submission, but the user will be unable to edit this field's value. This field type is useful if you are automatically populating a field, e.g. using parameters in the URL or using an autocomplete field.
Hidden	A hidden field. This will be hidden from the user, but will be passed in the form submission. This field type can only be populated using parameters in the URL or using an autocomplete field.

Default values

Providing a default value will pre-populate the field in your form when it initially loads. This enables you to provide a value to hidden and read only fields, and to default the status of radio buttons and checkboxes.

You can also use URL parameters and data you've surfaced using the pre-action layer as default values, enabling you to populate fields with data that's conditional to the current user.

Populate fields with URL parameters

As with many actions in Action Links, you can automatically populate the fields in your forms by including parameters in the URL for your Action Link. These parameters (sometimes called 'query parameters' or 'search parameters') consist of a series of key/value pairs that are appended to the end of the URL, like this:

https://demo-organisation.action.link/my-form?constituentId=123&email=[e-mail]

Notice that we include a question mark (?) before our parameters – this tells the user's browser that the address part of the URL has ended and that the rest of the URL should be treated as parameters. To populate fields in your forms, give the name of the field as the key, followed by an equals sign (=), followed by the value with which you want to populate the field. You should separate your parameters with an ampersand (&).

For security reasons, only parameters that have been added to the Allowed URL parameters section of the settings for your Link will populate the relevant field – this is to avoid a user constructing a URL that populates fields you don't want them to be able to. Provided the constituentId and email fields have been allowed, the above example will populate the constituentId field with 123 and the email field with [e-mail].

Use a consistent naming convention for field names It's always a good idea to use a consistent naming convention for your field names so that they're easier to understand and remember. You should avoid including spaces in your field names – we recommend using 'camel case', i.e. starting names with a lowercase character and then capitalising the first letter of all successive words (e.g. emailAddress or constituentId).

Populating fields with surfaced data

When surfacing data from integrated systems, you can use this data to populate the default values of your fields. To do this, simply use the Handlebars syntax in the default value field, e.g. {{tessitura.firstName}}. Note, you need to have added the parameter to the list of parameters to be surfaced for the Link.

Placeholders

A placeholder is an example that displays in a form field before a user begins their own input. Placeholders are really important for conveying the nature and structure of the field value that a user is expected to provide. As discussed below, users will often visually scan a form and complete fields without reading field labels – placeholders can help users to quickly assess what a field is asking for.

Avoid using placeholders that convey bias Where possible, placeholders should be relatively generic to avoid conveying bias. For example, for an email field it's usually better to use a generic example (e.g. [e-mail]) rather than a more specific example (e.g. [e-mail]) as this may be distracting. You can, however, use placeholders to guide a user, e.g. to providing a workplace email address (e.g. [e-mail]).

Help text

Help text displays below the relevant form field and is intended to give users additional context about how to complete a particular field. This is not a required field, and you should only use this to provide relevant additional information (to avoid cluttering your form and making it harder for your users to complete).

Prefix icons

For some forms you can choose to display a prefix icon inside an input field. This can make your forms easier for a user to complete, by adding a visual marker that helps them to navigate the form.

Prefix icons should use the Iconify icon reference, but replacing the colon (:) that separates the library and icon with a forward slash (/). So, for example, if you wanted to include an envelope from the Font Awesome library, instead of writing this:

fa6-regular:envelope

You would instead write your icon reference like this:

fa6-regular/envelope

You can find out more about using icons in Action Links from the Icons article, including how to search for relevant icons to use in your interfaces.

Icons help users to complete forms more quickly Have you ever tried to complete a payment form and realised that you've put the card number in the name field? User Experience (or UX) is often dependent on how intuitive your forms are. The average user will attempt to complete a form without actually reading all of the field labels, instead scanning the form and using visual patterns such as field widths, icons, and the order of the fields to make assumptions about what they're being asked for. Action Links gives you control over these patterns so that you can improve the UX of your own forms.

Custom validation criteria

Custom validation criteria enables you to set requirements for how your users should complete individual fields, e.g. to denote whether they are required to provide a value, and any formatting requirements, etc.

When using our form builder actions, we provide you with a wide range of options to add validation to your form fields, many of which you can see below. You can combine multiple validation criteria by separating the references with a pipe (|). So, for example, if I wanted a field to be required, and to only accept number values, and only values between 0 and 10, I would write my criteria like this:

required|number|between:0,10

Here's a list of validation criteria that you can use:

Rule	Details	Example
Required	A value must be given.	required
Accepted	The value given must be yes, on, 1 or true – intended to be used for checkboxes where a user must accept terms.	accepted
Alpha	The value must only use characters from the alphabet (includes most accented characters).	alpha
Alphanumeric	The value must only use letters or numbers.	alphaneumeric
Alpha-spaces	The value must only use letters, numbers, or spaces.	alpha_spaces
Between	The value must be between two numbers (inclusively).	between:0,10
Confirm	The value must be the same as that of another field (provide the name of the field you want to validate against).	confirm:password
Contains alphanumeric	The value must contain at least one letter or number.	contains_alphanumeric
Contains lowercase	The value must contain at least one lowercase letter.	contains_lowercase
Contains numeric	The value must contain at least one number.	contains_numeric
Contains symbol	The value must contain at least one special character.	contains_symbol
Contains uppercase	The value must contain at least one uppercase letter.	contains_uppercase
Date after	The value must be a date after the given date.	date_after:2020-01-01
Date before	The value must be a date before the given date.	date_before:2020-01-01
Date between	The date must be between the given dates. You can also pass JavaScript functions to calculate dates using the array syntax, e.g. to pass the current date you could use new Date().	date_between:2000-01-01,2020-01-01 [['date_ between', '1900-01-01', new Date()]]
Date format	The date must be in the given format. Formatting options include D/DD/M/MM/YY/YYYY	DD/MM/YYYY
Email	The value must be a valid email format.	email
Ends with	The value must end with the given substring.	ends_with:.ac.uk
Length	The value must be between the given lengths.	length: 0,10
Lowercase	The value must only contain lowercase letters.	lowercase
Matches	The value must match one of the given values or RegEx pattern.	matches:banana,pear,apple matches:/[a-z]/
Not	The value must not be one of the given values.	not:home,work
Number	The value must only contain numbers.	number
Starts with	The value must start with the given substring.	starts_with:@
Uppercase	The value must only contain uppercase letters.	uppercase
URL	The value must be a valid URL.	url

If escaping definition characters, use the array syntax If you need to escape the special characters used to define the validation criteria – pipes (|), commas (,) and colons (:) – you'll need to use the alternative array syntax to define your criteria. Instead of writing your criteria as a pipe-separated list, write it as an array of arrays, e.g. [['required'], ['matches', '10,000', '20,000']]

Field conditions

Field conditions enable you to affect the visibility of individual fields based on a user's response to another field. In this way, you can define logic to hide any questions that are only relevant to a specific subset of your users, as determined by their response to another question in the form.

If you set conditions for a field, the field will only display if all of the conditions you've set are met. Conditions will be assessed in the order they're defined, and once an unmet condition is encountered the remaining conditions will be ignored. For performance reasons you should therefore try to order your conditions with the narrowest (i.e. the least likely to be met) condition first.

Field	Details
Name	The name of the field you want to base your condition on – this is the name that you've defined for another field in your form.
Operator	The operator to use when assessing the status of the field (e.g. whether it's empty), or to compare the user's value for the named field against the value you provide.
Value	If applicable, a value to compare against the user's value for the named field, using the operator you've selected for the comparison.

Avoid using the same name for multiple fields

To avoid unexpected behaviour, make sure you only use a particular name for a single form field. If there is more than one field with the same name attribute, Action Links' default behaviour is to retain the value of the most recently updated field. However, if you apply conditions to show/hide one of these fields based on the value of another field, it can result in the fields with this name momentarily being removed from the page, which will prevent a value being set for that name going forwards.