Toggle menu

Form Functions, Handlers and Signatures

Your form and its fields can include JavaScript functions that are executed as the form, page, or individual fields load. You can also write handlers that are triggered by certain events, and use various types of validation to check or manipulate field values and data.

Execution Order

The forms designer lets you add JavaScript to your form that is executed at particular points in a form's lifecycle. The The Form Lifecycle: Control and Action Processing describes how forms are rendered and their actions processed, and The Form Helper Library has more information about writing functions.

This table describes each function/handler. They are executed in order, with those at the top of the table first.

Function/HandlerExecutedDescription
Form Server-side Initialisation HandlerServer-sideThe server-side initialisation handler found in the Form Settings menu. This is the first function to be executed before the page is rendered. It will be executed on every page. As this handler needs to take into account all pages, the Page Handler is often easier to use
Page Server-side Initialisation HandlerServer-sideThe server-side initialisation handler found in each page's settings. This function is executed after the form-level handler but before field default functions
Default FunctionsServer-sideAlmost every field can have a default function. This property lets you enter a script that will be executed server-side as the field is generated.

It is mostly used to set the value of the field. That could be by calling another service (an end point for example) or by calculating the value based on what's been entered in previous pages of the form
Form Client-side Initialisation HandlerBrowser-sideThe form client-side initialisation handler.

Allows you to enter script that is executed browser-side on every page once the page has been rendered. As this field needs to take into account all pages, the Page Handler is often easier to use
Page Initialisation Client-side HandlerBrowser-sideThe page initialisation handler.

Allows you to enter script that is executed browser-side once the page has been rendered. It is useful for showing and hiding multiple fields on a page
Validation FunctionBrowser-side repeated Server-sideAlmost every input field has a validation function. This property lets you enter a script that will calculate whether the value of the field is valid or not.

Validation is performed browser-side as field values are updated, and repeated server-side between pages and when the form is submitted (in which case a failure will reload the page and display the error). They return true for valid, false for invalid
HandlersBrowser-sideField handlers are executed browser-side on page load and are also triggered whenever the value of the field changes. Whether the value of a field is valid or not is passed to the handler function as a parameter.

The scripts you enter here will power much of the dynamic behaviour of your form. Handlers can be used to show and hide fields, update field values, disable fields, change the options available in drop-downs, to name just a few

Handlers have built in protection against circular events to prevent one field updating another, which then attempts to update the original field again

Function Signatures

Definitions

The following parameters are passed to the various functions described below.

NameDescription
contextContains any context variables
currentValueThe current value of the field, this may be undefined if the page on which the field is displayed as not been submitted
defaultPage Used in navigation functions. The page that would be navigated to if this function wasn't present
defaultPageInstanceUsed in navigation functions. The page instance that would be navigated to if this function wasn't present
defaultValueThe default value of the field. This is normally the value of the DEFAULT property
eventNameEither "CHANGE" (the value has changed), "NEWPAGEINIT" (the page is loading for the first time) or "PAGEINIT" (the page is loading)
fieldNameThe name of the field firing the event
helperThe form helper library
modeWhether the form is being rendered in:
normal - The standard mode for forms displayed on your site and in iCM
readonly - This mode is used when you "view" an article (as opposed to editing an article) and when a form is used to display form data saved in a history event
readonlynoctrl - Used by the forms data browser in iCM and when displaying form content in emails and elsewhere using the {{{RENDEREDFORM}}} helper
pageInstanceThe instance number of the page, this will be 0 for a new page, 1 for a page that exists in the form session data (ie a page that has been submitted)
pageNameThe name of the page about to be displayed
processorThe skeleton processor
propsContains any properties
sessionDataThe current session data storing (amongst other things) the values of fields submitted so far
validReturns true if the field passed validation, false if it failed
valueThe new value of the field

Form Level Server Init Handler: FORMINITHANDLERSERVER

A form level property containing a server-side initialisation function. It must be a function.

function(helper, pageName, pageInstance, mode) {
    // Perform any initialisation...
    if (mode === "normal") {}
}

Form Level Client Init Handler: FORMINITHANDLER

A form level property containing a browser-side initialisation function. It must be a function.

function(helper, pageName, pageInstance) {
}

Page Level Server Init Handler: PAGEINITHANDLERSERVER

A page level property containing a server-side initialisation function. It must be a function.

function(helper, pageName, pageInstance, mode) {
    // Perform any initialisation...
    if (mode === "normal") {}
}

Page Level Client Init Handler: PAGEINITHANDLER

A page level property containing a browser-side initialisation function. It must be a function.

function(helper, pageName, pageInstance) {
}

Button - Wizard: NEXTFUNCTION

A field level property on the wizard button field to calculate the next page. It must be a function. The function should return the name of the page to display.

function(helper, defaultPage, sessionData, defaultPageInstance) {
      return defaultPage;
}

Button - Wizard: BACKFUNCTION

A field level property on the wizard button field to calculate the previous page. It must be a function. The function should return the name of the page to display.

function(helper, defaultPage, sessionData, defaultPageInstance) {
      return defaultPage;
}

Button - Navigation: NAVFUNCTION

A field level property on the navigation button field to calculate the page to navigate to. It must be a function. The function should return the name of the page to display.

function(helper, defaultPage, sessionData, defaultPageInstance) {
    var thePage;
    // set the page to go to...
    return thePage;
}

Button - Navigation: SHOWFUNCTION

A server-side field level property on the navigation button field to determine if the button should be shown. It must be a function. The function should return true to show the button.

function(helper) {
    var showButton = true;
    // determine if button should be shown...
    return showButton;
}

Button - Script Button: SCRIPT

The code to execute when the script button is pressed. It must be a function.

function(helper) {
}

Field - Default Function: DEFFUNC

A field level property available on some field types. It must be a function. The function should return the value of the field. Without a default function this would be the defaultValue if currentValue is undefined, otherwise the currentValue.

function(helper, defaultValue, currentValue) {
    var theValue;
    if (currentValue !== undefined) {
        theValue = currentValue;
    } else {
        theValue = defaultValue;
    }
    return theValue;
}

Field - Event Handlers: HANDLERS

A field level property available on many field types. It must be a function.

function(helper, fieldName, value, valid, eventName) {
    if (eventName == 'CHANGE' && valid) {
        // perform action...
    }
}

Field - Validation Function: VALFUNC

A field level property available on many field types. It must be a function. The function should return true if the field value is valid, false if it is invalid.

function(helper, value) {
    var isValid = true;
    return isValid;
}

Layout - Conditional Layout: CONDFUNCTION

A field level property on the conditional layout field type. It must be a function. The function should return true to render the contained fields, false to ignore them. Note that fields in the layout are not simply hidden, they are not present on the form at all.

function(helper) {
    var showFields = true;
    return showFields;
}

Action - Script Action: ACTIONFUNC

Code to execute server-side when the form is submitted. It must be a function.

function(helper, processor, props, context) {
}

Last modified on 30 January 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon