Form Functions, Handlers and Signatures

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.

As each page of your form is requested, loaded, interacted with and submitted, the following cycle takes place.

The cycle starts at the top, with a browser making a request to your site for a form. The form is then rendered in the first blue block, and appears to the user at the beginning of the first green block.

The following parameters are passed to the various functions described in this document.

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.

Alternatively, return an object with the keys isValid and errorType to pass custom errors to the error message function.

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

Field - Error Message Function: ERRMSGFUNC

Used to generate a custom error message, depending upon the errorType thrown by the field. See Error Message Functions for a full description.

function(helper, errorType, defaultErrorMessage) {
    var errorMessage = defaultErrorMessage;
    // set error message based on errorType...
    return errorMessage;
}

Field - Options Function: OPTIONSFUNC

Used in the radio group, checkbox group, list box and drop-down list field to generate the options displayed.

function(helper, optionData) {
    // update optionData...
    return optionData;
}

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;
}

Layout - Accordion Layout: COLLAPSEDFUNC

A field level property on the accordion layout field. It must be a function. Return "collapsed" or "expanded" to control the behaviour of the layout when first displayed.

function(helper) {
    // The collapsed state can be either "collapsed" or "expanded"
    var collapsedState = "collapsed";
    return collapsedState;
}