Form HTML Structure and CSS Classes

This article looks at the HTML generated by iCM forms, their structure, the container, input and button fields, and how error messages are displayed. It includes details that will be useful if you are developing custom CSS or a theme for your site.

The examples in this article are subject to change. While we always try to make any changes backwards compatible, especially when you are using our form functions and CSS classes, items like IDs, names and types could change.

You should never target elements in the DOM directly with libraries like jQuery. If you do you will have to be prepared to check, test and update your custom work as we release new versions.

Basic Form Structure

The sample below shows a simplified outline of a form.

<form id="#FORM_NAME#_FORM"> <div id="#FORM_NAME#__FIELDS_OUTER" class="icmform #ALIGNMENT#"> <ol role="presentation"> <li role="presentation" id="#FORM_NAME#_#FIELD_NAME#_OUTER">...</li> <li role="presentation" id="#FORM_NAME#_#FIELD_NAME#_OUTER">...</li> <li role="presentation" id="#FORM_NAME#_#FIELD_NAME#_OUTER">...</li> </ol> </div> </form>

#FORM_NAME# is the unique name given to the form in the forms designer.

#FIELD_NAME# is the unique name given to a form field in the forms designer. For multi-page forms this field name will also include the name of the current page.

#ALIGNMENT# is one of icmformleft, icmformright or icmformtop and is controlled by the form's "Alignment" property in the forms designer.

Each field on a form is represented as a single list item within the containing ordered list.

Classes on the form's outer div are used to specify the general form layout/styling.

The site's form style sheet should use these classes to ensure that an iCM form lays out using the correct alignment, ie left-aligned labels for icmformleft, top-aligned labels for icmformtop, or right-aligned labels for icmformright.

Container Field Structure

As with the overall layout, each container field is represented by a list item in an ordered list.

<fieldset class="#LAYOUT_CLASS# #SHOWBORDER_CLASS#"> <legend> <span>#CONTAINER_LABEL#</span> </legend> <ol role="presentation"> <li role="presentation" id="#FORM_NAME#_#FIELD_NAME#_OUTER">...</li> <li role="presentation" id="#FORM_NAME#_#FIELD_NAME#_OUTER">...</li> <li role="presentation" id="#FORM_NAME#_#FIELD_NAME#_OUTER">...</li> </ol> </fieldset>

#LAYOUT_CLASS# is one of icmvertical or icmhorizontal depending on the intended layout of the fields within the container.

#SHOWBORDER_CLASS# is either icmshowborder or icmhideborder depending on the Show Border property of the layout field.

#CONTAINER_LABEL# is the container field's label as specified via the 'Label' setting within the Forms Designer.

Note that within iCM the horizontal layout behaves like a "flow" layout, in that fields wrap to the next line if they don't fit horizontally.

If "Show Label" is set to false in the forms designer, an additional icmhide class will be added to both the legend and the fieldset. This class should be used by the site's form style sheet to apply styling that hides the fieldset label.

For example, this vertical container has both it's border and label hidden:

<fieldset class="icmvertical icmhide icmhideborder"> <legend class="icmhide"> <span>Vertical container</span> </legend> <ol role="presentation"> <li role="presentation" id="TESTFORM_FIELD1_OUTER">...</li> <li role="presentation" id="TESTFORM_FIELD2_OUTER">...</li> <li role="presentation" id="TESTFORM_FIELD3_OUTER">...</li> </ol> </fieldset>

Radio Button and Checkbox Groups

Radio button and checkbox group field types are containers, so follow a similar structure to the container fields above. They also have the following classes on the fieldset tag: icmbuttongroup and either icmradiocontainer or icmcheckcontainer.

These additional classes are provided to enable these button/check groups to be distinguished from the basic vertical and horizontal containers.

The following sample HTML was generated for a radio button group whose border and label have both been hidden:

<fieldset class="icmvertical icmbuttongroup icmhide icmhideborder icmradiocontainer"> <legend id="TESTFORM_FIELD1LABEL" class="icmhide"> <span>Radio Button Group</span> </legend> <ol> <li> <input type="radio" id="TESTFORM_FIELD1_OPT0" name="TESTFORM_FIELD1" value="1"> <label for="TESTFORM_FIELD1_OPT0">One</label> </li> <li> <input type="radio" id="TESTFORM_FIELD1_OPT1" name="TESTFORM_FIELD1" value="2"> <label for="TESTFORM_FIELD1_OPT1">Two</label> </li> </ol> </fieldset>

Input Fields

Non-container input field types (text, number, drop-down list etc) typically include a label and some form of HTML input control. Assuming a field type that uses the HTML input element, the following HTML structure would be generated:

<div id="#FORM_NAME#_#FIELD_NAME#_OUTERDIV" class="#FIELD_CLASS# #FIELDWIDTH_CLASS# clear"> <label for="#FORM_NAME#_#FIELD_NAME#" id="#FORM_NAME#_#FIELD_NAME#LABEL"> #FIELD_LABEL# </label> <input type="#FIELD_TYPE#" id="#FORM_NAME#_#FIELD_NAME#" name="#FORM_NAME#_#FIELD_NAME#" value="" class="#WIDTH_CLASS_PREFIX##WIDTH_CLASS_SUFFIX#"> </div>

#FIELD_TYPE# is the field's type, for example text, number or textarea.

#FIELD_CLASS# is "field_#FIELD_TYPE#" for example field_text or field_number.

#FIELDWIDTH_CLASS# is "fielddiv_#WIDTH_CLASS_PREFIX##WIDTH_CLASS_SUFFIX#" for example fielddiv_icmtext.

#WIDTH_CLASS_PREFIX# is controlled by the field's width property in the forms designer and will be one of:

icmvs Very short
icms Short
icm Medium
icml Long
icmf Fit

#WIDTH_CLASS_SUFFIX# is usually the same as the field type, but there are exceptions to this rule so always check. For example, text is also used by the Number and Date Input field types.

The class assigned to the field's outer div can be used to distinguish one type of input field from another.

The width class assigned to the input control itself, and the width class assigned to the outer div, should be used by the site's style sheet to ensure the field is sized appropriately.

The values of other field properties set in the forms designer may modify the structure slightly. For example, setting a field as "Required" append <em title="required">*</em> to the end of the label tag's content.

Here's the HTML generated for a number field that is required and has a "short" width:

<div id="TESTFORM_FIELD1_OUTERDIV" class="field_number fielddiv_icmstext clear"> <label for="TESTFORM_FIELD1" id="TESTFORM_FIELD1LABEL"> Number<em title="required">*</em> </label> <input type="text" id="TESTFORM_FIELD1" name="TESTFORM_FIELD1" value="1 class="icmstext" aria-required="true"> </div>

This is a "long" drop-down list which is not required:

<div id="TESTFORM_FIELD1_OUTERDIV" class="field_select fielddiv_icmlselect clear"> <label for="TESTFORM_FIELD1" id="TESTFORM_FIELD1LABEL"> Drop-down List </label> <select id="TESTFORM_FIELD1" name="TESTFORM_FIELD1" class="icmlselect"> <option value="1" selected="selected">One</option> <option value="2">Two</option> <option value="3">Three</option> </select> </div>

The styling applied to the different width classes should be consistent across the different field types - a "Short" text field should have the same width as a "Short" list box.

Button Fields

All of the button fields use the same HTML wrapper to make styling consistent.

<div class="icmbutton-surround #FIELD_TYPE#"> <div class="icmbutton"> ... </div> </div>

#FIELD_TYPE# will be one of submit, reset, script, wizard etc.

The HTML of a submit button looks like this:

<div class="icmbutton-surround submit"> <div class="icmbutton"> <button class="btn btn--form btn--submit" type="submit" value="BASICTOP_FIELD2406" id="BASICTOP_FIELD2406_FINISH" name="BASICTOP_FORMACTION_FINISH" data-id="BASICTOP_FIELD2406" data-label="Submit" onclick="return BASICTOPForm.onFormSubmission( 'FINISH', true )">Submit</button> </div> </div>

Any buttons nested inside more complex field types will generally follow this structure.

The HTML generated for the Wizard button field type, for example, is made up of one or more buttons wrapped in an additional div, as follows:

Inline Error Display

If a field fails validation, additional HTML mark-up and classes are added to the standard field structure to provide an in context error display.

In the documentation above is the HTML for a number input field. If this field failed validation, the HTML would become:

<div id="TESTFORM_FIELD1_OUTERDIV" class="field_number fielddiv_icmstext error"> <div id="TESTFORM_FIELD1_ERRORBLOCK" class="errorblock" role="alert"> <ul role="presentation"> <li>Invalid number specified</li> </ul> </div> <label for="TESTFORM_FIELD1" id="TESTFORM_FIELD1LABEL"> Number<em title="required">*</em> </label> <input type="text" id="TESTFORM_FIELD1" name="TESTFORM_FIELD1" value="1 class="icmstext" aria-required="true" aria-invalid="true" aria-describedby="BASICTOP_FIELD2290_ERRORBLOCK"> </div>

Notice the the field's outer <div> now includes an additional error class

The error information is included as an additional nested <div> whose identifier follows the format: #FORM_NAME#_#FIELD_NAME#_ERRORBLOCK. Each error message is displayed as a new <li> within this nested error block.

Be aware that the validation errors field type (below) also uses the errorblock class.

Error Display Block

The forms designer also includes a validation errors field type, which can be used to display the errors from all of the fields in one place. It generates the following HTML:

<div id="TESTFORM_FIELD1_OUTERDIV" class="field_valerrors clear"> <div id="TESTFORM_FIELD1_ERRORBLOCK" class="errorblock"> <fieldset class="icmvertical"> <legend><span>Form Errors</span> </legend> <ol id="TESTFORM_FIELD1_OL" class="field_valerrors" role="presentation"> <li id="TESTFORM_FIELD1_LI_FIELD2" role="alert"> <strong id="TESTFORM_FIELD1_LI_FIELD2">Field Two's Label</strong> <ul id="TESTFORM_FIELD1_UL_FIELD2" role="presentation"> <li>Invalid</li> </ul> </li> <li id="TESTFORM_FIELD1_LI_FIELD7" role="alert">...</li> </ol> </fieldset> </div> </div>

The errors are inside a nested <div> with an identifier in the format: #FORM_NAME#_#FIELD_NAME#_ERRORBLOCK

A layout similar to the vertical container is used, with each list item containing a nested unordered list that displays one or more errors for a particular field.

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: