Forms Scripting Scope of Variables

These tables cover the various places with the form model that scripting is allowed, and describe the default script variables that are in scope in those places.

Note: When setting a control value via the "f" array, the changes are not realized until the whole action script ends. This means that any bindings or rules that are tied to the updating of that control is not triggered until the whole script finishes. Use the setValue() method for the control whose value you are modifying.

The "f" array and "p" array functionality is deprecated. You can use control.<control-name>.getValue() instead of using "f" array and use p.get<parameter-name> instead of using the "p" array. See the table Action for details.

Action

Variable  Description 
context
read-only.
This is a data structure that provides access to the context under which the action is invoked. There are 6 fields available within this variable:
  • context.control:
    The control object that was the source of the event that triggered the rule. If the source was not a control, then this field is null.
  • context.form:
    The form object where the event originated.
  • context.oldValue:
    Provides the old value if this is a control or parameter update event.
  • context.newValue:
    Provides the new value if this is a control or parameter update event.
  • context.pane
    : The pane object that was the source of the event that triggered the rule. If the source was not a pane, then this field is null.
  • context.record:
    This field is provided within the computation actions where the destination control or pane is under a collection pane (grid or record pane). The record corresponds to the object in the destination control's (or pane's) parent pane value. For example, when you are computing the value of a control at the 6th row of a grid pane, the record points to the complex object at index 5 of the grid pane value. This field can also be used within validations. 
control
 Use control.<control-name> to access any control defined within the form. 
data
 Use data.get<param-name> to access the values of form parameters or data fields. This method returns either a primitive value for simple types such as Text and Boolean, or instances of objects when the type is defined in a BOM. For primitive types, data.set<param-name> is also available. 
factory
 Use factory.<package-name> to access factories based on packages defined within the business object models available to the form. These factories allow you to create new instances of classes defined in that package. 
pane
 Use pane.<pane-name> to access any pane defined within the form. 
pkg
 Use pkg.<package-name> to access package objects based on packages defined within the business object models available to the form. The package object allows you access definitions of Enumerations defined within the package. 
resource
 Use resource.<external-resource-name>.<property-name> to access the localized values from property files. A property file can be added to the Presentation Resources folder and it can be referenced from a form by creating an External Resource in the form. For example: when a property file in the Presentation Resources folder is added as an External Resource in the form with the name resource1, all the properties in that file can be accessed in a user-defined form action script from the object returned by resource.resource1. Thus if the property file contains a property with name name1, the value of this property can be retrieved in a user-defined script as: resource.resource1.name1.

If a localized bundle is provided and a value exists for the property in that bundle, the value from that bundle is returned. If the property is missing in the localized bundle, the value from the base bundle is returned.

Use resource.mappings.<parameter-name> to access the values in the data mappings file of the form. These keys represent the properties to which all the controls or panes in the form are bound. The Form Designer automatically generates the data mappings file in the Presentation Resources folder, and it can be referenced from a form as an External Resource. For more information, see Data Mappings File . 

f
 read-only. Field value array that accesses the current values of controls in the form. Field values can be accessed using f.controlName. Field values can be updated by assigning a new value to them. Example: f.foo=’newValue’;

Deprecated. Use control.cn.setValue(cv) instead of f.cn = cv;        and var cv = control.cn.getValue(); instead of var cv = f.cn; 

p
 read-only. Parameter value array that accesses the inbound values of parameters. p can replace a pane and control. Parameter values can be accessed using p.paramName.

Deprecated. Use data.setPn(pv); instead of p.pn = pv; and var pv = data.getPn(); instead of var pv = p.pn; 

this
 read-write. For actions that are initiated from a control event, this refers to the control object from which the event is initiated. From this, access the form object and other controls and make updates to the state of the form model.

Deprecated. Use the new context variable that is available within the script.

Validation

Variable  Description 
f
 read-only. Field value array that accesses the current values of controls in the form. Field values can be accessed using f.<control-name>.

Deprecated. Use var cv = control.cn.getValue(); instead of var cv = f.cn;. 

this
 read-only. Refers to the control object upon which the validation is configured. From this, access the form object and other controls, although no updates to the form model are allowed within a form validation script.

Deprecated. Use context.value to get the value of the control being validated. 

context
 read-only. Within the scope of a validation script, the context variable supports only the following field:

context.value: This is equal to the value of the control being validated. If the control is multi-valued, such as a text control with the list setting enabled, then the validation is run once for each value in the list. 

resource
 User-defined validation scripts can retrieve localized values from property files using the resource variable. The resource details provided in the table Action are also applicable for validation scripts.