All of the fields on your form are identified by a name. Field names must be unique across all of the pages of your form.
Adding a Field to a Form
When you add a field to a form it is automatically given a unique name. The names iCM generates all have the format, FIELDn - with n being a number that goes up by one for each field on your form.
Select a field and view its settings to see its name.
Names and Labels
We recommend giving all of the fields on your form meaningful names. This makes them easier to work with in the JavaScript and Handlebars templates your form might use. It also makes debugging easier if something goes wrong. Field names are always saved in upper case and can only include letters and numbers.
Labels appear next to your form fields when the form is published on your site (most fields also have options that let you show or hide their labels).
When you first rename a field, the name is copied into the label property, hopefully saving you time if the field name and label are going to be the same. For example, "FIELD13" in the screenshot above, is renamed "email". The name is put into upper case and automatically copied into the label property.
If you enter your field names in CamelCase, the label will be copied across in sentence case, so a field name entered as "FirstName" will create the label "First name".
Long and Short Field Names
This section describes an advanced feature of the forms designer that is rarely used - skip over it for now!
There's a more detailed look at forms that use external type definitions in the Forms and External Type Definitions knowledge base article.
If a form uses an external type definition, its fields will have two names.
"Long" names include the external type prefix. "Short" names exclude the prefix.
If you have worked with versions of iCM prior to 10.0.7.0 you'll be familiar with the "long" field names. These names include the name of the form/type the field is being mapped to.
Working with Field Names
If the form in the screenshots above used an external type called TIMSFORM, the email field's name would have to be selected from one of the available names in that external type. You can see below that they are all prefixed with FORM_TIMSFORM, so the email field's true name is FORM_TIMSFORM.EMAIL.
To make working with forms that use external types easier, iCM lets you use the field's short name in your form JavaScript and Handlebars. iCM recognises the short field name, knows that your form uses an external type, and is able to convert short names to long names (or long names to short names).
So, if we want to update the email field FORM_TIMSFORM.EMAIL in a JavaScript handler, we can reference it like this:
or in JavaScript:
function (helper, fieldName, value, valid, eventName) {
if (eventName == 'CHANGE' && valid) {
helper.setFieldValue('EMAIL', 'support@gossinteractive.com');
}
}
When you select a field in the visual script editor, you can see the long and short names.
Short field names can also be used in your Handlebars templates. A default summary template for the form above would look like this:
<div class="icmformdata">
<h1>Tims first form with an external type</h1>
<h2></h2>
<table class="icmformdatapagetable">
<tbody>
<tr>
<td colspan="2" class="icmformdatacontainer">Label</td>
</tr>
<tr>
<td class="icmformdatalabel">Email</td>
<td class="icmformdatavalue">{{FIELD "EMAIL"}}</td>
</tr>
<tr>
<td class="icmformdatalabel">First Name</td>
<td class="icmformdatavalue">{{FIELD "FIRSTNAME"}}</td>
</tr>
<tr>
<td class="icmformdatalabel">Family Name</td>
<td class="icmformdatavalue">{{FIELD "FAMILYNAME"}}</td>
</tr>
<tr>
<td class="icmformdatalabel">Address</td>
<td class="icmformdatavalue"><pre>{{FIELD "ADDRESS"}}</pre>
</td>
</tr>
<tr>
<td class="icmformdatalabel">Location</td>
<td class="icmformdatavalue">{{FIELD "LOCATION"}}</td>
</tr>
</tbody>
</table>
</div>
See the Handlebars Editors article for more information about these templates.
Changing External Types
If you change the external type definition your form uses, iCM will attempt to map field names from your existing form to fields in the new type definition.
Our example form has had its external type changed to a new form called FORM_ANOTHERFORM. The new type definition includes a field called EMAIL so the email field has been mapped to it.
No matches could be found for the First Name and Family Name fields. They are highlighted in red and need to be assigned manually.
When you change external types iCM automatically searches all of the JavaScript, HTML and Handlebars code for references to the old external type. Results are displayed using the standard search panels.
If your JavaScript and Handlebars templates are using short names, or are built using the visual script editor, these won't need to be updated - the change of prefix is handled by iCM.
Share this page
