Toggle menu

Form Settings

The Form Settings section of the forms designer lets you control how the whole form behaves, including field alignment, when validation is performed, the form's content type, whether tracing and debugging is enabled, and supply custom code, read-only modes and an initialisation handler that is loaded with each page.

There's more information about form and page init handlers and the order they are executed in in the Form Functions, Handlers and Signatures article.

PropertyDescriptionType Name
AlignmentWhether field labels appear to the left, right or above their fields. This adds one of icmformleft, icmformright or icmformtop as a CSS class to the formALIGN
ActionThe URI of the server-side form handler. When the form is submitted, this is the program that will handle the completed and submitted form. The content type and protocol used to transmit the data is determined by the Encoding and Method settingsACTION
EncodingThe default is automatic, which will switch the encoding to multi-part if a file upload field is present in the form.

URL Encoding (enctype="application/x-www-form-urlencoded"). This should be suitable provided that neither large amounts or binary (non-alphanumeric) data is to be transmitted.

Multi-part encoding (enctype="multipart/form-data") should be used for submitting forms that contain files, non-ASCII data, and binary data
MethodThe HTTP method by which the form data will be submitted. 

The HTTP "get" method appends the form data to the URI specified by the 'Action' setting and this new URI is sent to the server.

The "get" method should be used when the form is idempotent i.e. causes no side-effects. The HTTP "post" method includes the form data in the body of the form and sent to the server. If processing of the form causes side effects (for example, if the form modifies a database or subscription to a service), the "post" method should be used
On-SubmitA script executed after each page submission. Any JavaScript specified here will be included in the form's on-submit handler, preceded by a 'return' statement:

<form onsubmit="return [the entered JavaScript]">
FORM TagWhether to output the HTML FORM tag. Typically this setting should always be enabled, to allow the iCM forms to control output of the FORM tag. This setting is only included for backwards compatibility and its use should be avoidedFORMTAG
ValidationEither "As you type" or "On-submission" validation is available. The former will validate and mark invalid fields (and valid ones if 'Highlight Valid Fields' is enabled) as data is entered. The latter will only validate and highlight any errors when the form is submittedVALIDATION
Highlight Valid FieldsIf set as true, and validation is set as "As you type", fields that pass validation will be have "valid" added as a CSS classHIGHLIGHTVALID
Custom CodeThis property is included for backwards compatibility with the old form family. You should now provide custom JavaScript functions using a helper variable field or the Form/Page Init Handlers. There's an example in Writing a Custom Function.

Custom code should follow this format:

a = {
  method1: function(helper) { ... },
  method2: function(helper) { ... }
Client Init HandlerA client-side script executed on each page of the form. See Form Functions, Handlers and Signatures for a full explanation of the order in which the various handlers and functions are executedFORMINITHANDLER
Server Init HandlerA server-side script executed on each page of the form. See Form Functions, Handlers and Signatures for a full explanation of the order in which the various handlers and functions are executedFORMINITHANDLERSERVER
Disable Auto-focusThis can be used to disable the setting of the input focus to the first field on a form. Disabling the auto-focus can be useful if the form is preceded by a large amount of article text. This property also interacts with the helper enableAutoFocus and disableAutoFocus functions. These functions provide greater control if called from form or page level init handler functionsDISABLEAUTOFOCUS
Debug PanelWhether to display the form debug panel. See Debugging and Tracing for more information about using the debug panel. The panel should never be enabled on a public formDEBUGMODE
TracingEnable tracing. This controls the operation of the .trace function.  This function can be used to generate browser-side and server-side trace messages. If false no trace messages will be generated and calls to helper.trace are ignored. If true traces messages will be generated as follows:

Trace messages are output to the browser specific console. This is normally accessed via a 'Developer Tools' option from within the browser. If the form Debug Panel is enabled trace messages will also be output to the 'Console' tab of the debug panel

Trace messages are output to the API Server console log
Hint Text JustificationThe default justification of the hint textHINTJUSTIFICATION
Hint Text PositionWhether the field hint text should appear above the field inputs or below them. This setting is only relevant if your field labels are top aligned. If your labels are left (or right) aligned the hint text will always appear below the fieldsHINTPOSITION
Field Hint TextWhether to show or hide field hint textHINTDISPLAY
Custom Read OnlyA handlebars template that will be used to display this form when it is viewed in a read-only mode. Read-only modes are often used when viewing saved form data as part of a history or process instance via the Self Service products. Read-only modes also include the emails and PDFs generated by the email action field.

See Read-Only Forms for more information
Custom Read Only Data FunctionA data manipulation function, executed server-side, that can manipulate the JSON data supplied to the template before any HTML is generated. It is supplied with two parameters, a reference to the helper library and the current value of the JSON object. The second parameter is always supplied as a JavaScript JSON object. It will never be null or undefined.

The result of your function is available to the read only template in the "this" object
Field Label MarkerMark Required Fields - Fields set as "required" will have an asterisk next to their label
Mark Optional Fields - Rather than flagging required fields, fields that are not required will have the Optional Field Text (see below) next to their labels. GDS (the UK government's digital services department) have suggested this approach in their style guide
Optional Field TextThe text that will appear next to optional fields if you choose to mark fields that are optional rather than fields that are required. The default is (optional)FIELDLABELOPTIONALTEXT
Additional Styling ModifierAn optional CSS modifier for the form. This modifier is added to the main "outer" div of the form. For example:
Form Setting Styling Modifier
Would output:
<div id="FORMNAME__FIELDS_OUTER" class="icmform icmformtop icmform--formsettingsmodifier">
Modifiers are lowercased and cannot contain spaces. They can be targeted by your website theme or skin
DocumentationAdd documentation to your form to help explain any complex functionality to future users. You might include information on what the form does and, if it's part of a workflow process, how it relates to other forms. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. There's an example in the Common Field Properties sectionDOCUMENTATION
Last modified on 30 January 2024

Share this page

Facebook icon Twitter icon email icon


print icon