The following properties are common to many of the fields you'll find in the forms designer.
There's more information, and examples, in the Form Validation, Error Messages and Hints knowledge base article.
Name
Every field must have a unique name. When you first drag fields into the design area they will be named FIELD1, FIELD2, FIELD3 etc. Replacing these names with more meaningful values makes your form much easier to work with, because although names are not visible on your form, they are used in other places.
For example, when you write JavaScript or use the Visual Script Editor, all of the functions for querying fields use the field name. Field names are also used as the names of process variables in the workflow engine, in histories if your form stores data using the History Worker, and are used in iCM Objects and in the Form Data Browser. If you ever need to retrieve or delete data, knowing that an email address is stored in a field called EMAIL rather than FIELD47 makes the process much simpler.
Label
Labels appear alongside all fields that may be visible when your form is published. They let the user know what information you are expecting to be entered.
The labels on a form can be aligned to the left, right, or placed above the field they relate to. Alignment is set in the "Form Settings" section of the designer toolbox.
Show Label
Labels can be shown or hidden by setting the "Show Label" property as either true or false. You might want to hide labels on layout fields, or if accompanying guidance text explains what a field is for.
Hints
Input fields can have hints published alongside them, providing the user with more information about what should be entered. Hints are most commonly used when you expect data to be entered in a particular format.
For example, if you are using a postcode lookup and you've set up validation so that the postcode must be entered using capital letters, you could provide this information in a hint.
Hints can be shown or hidden when your form is first displayed using the "Field Hint Text" property in the "Form Settings". There's also a property to set the hint text justification as left, right, centred, or fully justified, and whether you want the text to appear above or below the input field (hints can only appear above fields if the labels are top aligned).
Hints can be updated dynamically using .updateFieldHint, or shown and hidden using .showFieldHint and .hideFieldHint. Hints can also the value of another field by adding the field's name between # characters, or the value of a variable by adding the variable's name between % characters.
Required
Fields that have their "Required" property set as true must have a value entered before your form can be submitted. This low level validation simply checks that something has been entered, it doesn't check its format.
You can choose whether optional fields are marked as optional (the recommended approach) or required fields are marked, in the Form Settings.
It's not possible to dynamically change the required setting of a field. Instead you should use the validation function.
Error Messages
Field error messages are displayed if a required field is left empty, or if the value entered into a field fails validation. The default error message is "Invalid", but it's best to change this to something more meaningful.
You can dynamically generate error messages using Error Message Functions.
Rather than displaying error messages alongside each field, the Validation Errors field can be used to group them all together.
Validation can either be performed as the user is typing (ie, as soon as they move the cursor out of a given field) or when the form is submitted. This is controlled using the "Validation" property in the "Form Settings".
Default
Some fields can have a default value set in the form designer. This static value will be output in the field when the page is first loaded. If this value isn't changed by the user it will be submitted with the form data.
Autocomplete
This property adds the HTML
The default is Automatic (not set), which doesn't output the attribute and is treated as "on". This means the browser is allowed to automatically complete the input, but no guidance is provided as to the type of data expected in the field, so the browser may use its own judgement.
Default Functions
Default functions are JavaScript functions executed server-side as a field is loaded. The result of the function is used as the field's value.
Server-side processing means you are able to access more secure services that aren't directly available to the browser. These functions are also executed between the pages of a form, meaning you could use the values entered by a user on page one to call a service and display the result on page two.
In this default function, if the field doesn't already have a value, will call an end point using the value of the date field and set the result as the value of the field.
function(helper, defaultValue, currentValue) {
var theValue;
if (currentValue) {
theValue = currentValue;
} else {
theValue = helper.utilServerAPIServerCall('serverlibrary', 'trainingMapData', {
date: helper.getFieldValue('DATE')
});
}
return theValue;
}
Handlers
Field handlers are also JavaScript functions. They are triggered when the page first loads (after the default function) and whenever the value of the field changes.
Unlike default functions, handlers are only executed client-side, in the user's browser. This means they cannot access any services that are only available on the server (ie the majority of the API Server's worker services and any end points deployed to the server library).
Handlers are commonly used to show and hide fields, and to update the values of fields based upon other fields on the form.
This example is used on a radio button field with two options. Users can choose to be contact by email or phone, and an appropriate hidden field is revealed.
Validation Functions
Validation functions are another type of JavaScript function that can be added to a field. They are used solely to check that the value of a field is valid - they cannot change the value of a field.
Validation is performed client-side while the user is filling out the form (either as they complete each field or on submit) and repeated server-side so that it cannot be bypassed by malicious behaviour.
Additional CSS Modifiers
Almost every visible field type that gets output onto a page can have an additional CSS modifier applied to it. Non-visible fields (eg action fields, hidden fields, variable fields) don't have the property.
For example, this text input field has the value "mycustommodifier" as an additional styling modifier:
Which is output in the page source as:
class="icmltext icmltext--mycustommodifier"
Modifiers are lowercased and cannot contain spaces. They can be targeted by your website theme or skin.
Documentation
You can add comments to your form, each page, and each field type. These comments are only visible in the Forms Designer and are designed to provide information about what your form or field does, and explain any complex interactions to other users (or remind yourself!) when working on the form in the future.
For example, you might add a comment to a Form Helper variable field that said "Stores the result of a call to the goss.example end point in a server-side variable. The result is used on page 2 by the drop-down list and on page 3 by the checkbox field".
Documentation can be searched for and viewed in the left-hand action panel.
View Documentation
This action displays all of the documentation present in the form. If pages or fields don't have documentation they are ignored. You can also print the documentation, which most browsers will let you save as a PDF too.
Share this page
