Toggle menu

Field Names and External Types

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.

New Field 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 in title case.

Rename a Field

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 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.

Naming Fields - External Type

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:

Short Names in Blockly

or in JavaScript:

function (helper, fieldName, value, valid, eventName) {
    if (eventName == 'CHANGE' && valid) {
        helper.setFieldValue('EMAIL', '');

When you select a field in the visual script editor, you can see the long and short names.

Select Field

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>
    <table class="icmformdatapagetable">
                <td colspan="2" class="icmformdatacontainer">Label</td>
                <td class="icmformdatalabel">Email</td>
                <td class="icmformdatavalue">{{FIELD "EMAIL"}}</td>
                <td class="icmformdatalabel">First Name</td>
                <td class="icmformdatavalue">{{FIELD "FIRSTNAME"}}</td>
                <td class="icmformdatalabel">Family Name</td>
                <td class="icmformdatavalue">{{FIELD "FAMILYNAME"}}</td>
                <td class="icmformdatalabel">Address</td>
                <td class="icmformdatavalue"><pre>{{FIELD "ADDRESS"}}</pre>
                <td class="icmformdatalabel">Location</td>
                <td class="icmformdatavalue">{{FIELD "LOCATION"}}</td>

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.

New External Type Name Mapping

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.

Last modified on 06 June 2023

Share this page

Facebook icon Twitter icon email icon


print icon