Toggle menu

helper.setVariable(name, value [,scope])

Creates and sets the value of a form variable.

Form variables are named variables that can store values and objects. They are accessed using helper.getVariable, and can be created using helper.setVariable

If multiple forms are rendered on the same page they can have independent variables with the same name.

Executed

Client-side and server-side.

Arguments

ArgumentTypeDescription
nameString, requiredName of the variable to be set
valueAny, requiredThe value of the variable. This can be of any type, including objects, arrays and the values of other fields/variables
scopeString, optionalOne of:

helper.VARIABLE_SERVERONLY
helper.VARIABLE_SERVERCLIENT
helper.VARIABLE_SERVERCLIENTUPDATE
helper.VARIABLE_NONPERSISTENT

If no scope is set, helper.VARIABLE_NONPERSISTENT is assumed

Scope

Helper variables can be set with a scope, which defines where they will be available to use.

Note than once a helper variable has been created it is not possible to change its scope. If no scope is specified the default is NONPERSISTENT.

When working browser-side you can only create non-persistent variables. If you want your variable to be available server-side, available on the server and browser, or to be updated by actions on the browser and sent back to the server, it must first be created server-side. These restrictions ensure that it is not possible to create a new variable on the browser and have it stored in the form session.

helper.VARIABLE_SERVERONLY

The variable will be available to any functions executed server-side on any page of the form. Any changes made to its value in subsequent server-side functions will be saved.

The variable value is stored in the iCM database and will not appear browser-side, so it can be used to store more sensitive information if required. The value of the variable can be retrieved in the default functions of other fields.

helper.VARIABLE_SERVERCLIENT

The variable will be available to any functions executed server-side on any page of the form. Any changes made to its value in subsequent server-side functions will be saved.

It will also be available to any functions executed browser-side. Any changes made to the variable by browser-side functions will only be visible to the current page of the form. No changes made browser-side are submitted back to the server.

helper.VARIABLE_SERVERCLIENTUPDATE

The variable will be available to any functions executed server-side on any page of the form. Any changes made to its value in subsequent server-side functions will be saved.

It will also be available to any function executed browser-side. Any changes made to the variable by browser-side functions will be visible to the current page of the form and passed back to the server when the page data is successfully stored, making those changes available to subsequent pages.

helper.VARIABLE_NONPERSISTENT

The variable will be available to any function on the current page executed on the browser. It is not available to any server function and any changes made on the browser will not be submitted back to the server.

Example

In this example we're creating a variable called myVariable and giving it the value of hello. It will be available server-side and client-side, but changes to it won't be submitted back to the server.

function (helper) {
    helper.setVariable('myVariable', 'hello', helper.VARIABLE_SERVERCLIENT);
}

Last modified on 09 May 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon