Addressing

Addressing is supported in all views in the UI toolkit, including views that are nested within other views that are defined in a UI page.

The addressing scheme is a hierarchical, tree-like structure whose root is defined as / at the topmost position in the displayed page. The structure of the addressing scheme is similar to that used for a directory. Subsequent nodes in the tree are added as the page is loaded.

Two basic types of nodes are available, Container and Element. Container nodes include other nodes, such as elements, views, and other container nodes.
Restriction: The views in the deprecated Coaches toolkit are not addressable using the described addressing scheme.

Typically, you would use addressing in the UI views when there are functions that are called by view events or formulas that are used in some views. Functions can be specified inline, as in a JavaScript script block of a custom HTML on a page, or in the Inline JavaScript section in the Behavior properties of the view.

Addressing styles

Relative and absolute addressing styles are supported. Starting a reference with / implies an absolute reference, for example, starting at the root level of the view tree. Omitting the / at the beginning of the path means "from where I am". Using .. in a reference causes the reference to go back up a level, as a file directory tree would behave.

In a formula, references are computed from the reference point of the field whose formula you are setting:
  • Fields at the same level as the current one are referenced by using the field name (not using / at the beginning of the reference).
  • Fields that are one level above can be referenced as ../FieldOneLevelAboveMe.
  • Fields that are two levels above are referenced as ../../FieldOneLevelAboveMe, and so on.
  • Relative addressing using ../ can be convenient in some cases.

JavaScript methods to access views

From a Custom HTML
To access a view in a JavaScript block, use the page global view and its page.ui.get(ControlId path) method. For example, say you have a Text view named Text1 and, for validation purposes, you want to access it in a function that is called from an On click event of a button. To do so, use code that is similar to the following example:
var myTextField = page.ui.get("/Text1");
myTextField.getValue() // returns the value in the text field
myTextField.focus() // would set the focus to the text field.
From the inline JavaScript of a view
To access a view from a function that is contained in a container view, use one of the following options:
bpmEventHelper.ui.getView(ControlId [, thisview])
thisview.ui.get(ControlId)
where thisview is defined in the container view.
For example, say you have defined a container view that includes two views named Text1 and Select1 and, for validation purposes, you want to access the two nested views from a validateControls function that is called from an On click event of a button in the parent view. To access the views, place code similar to the following example in the inline JavaScript section on the Behavior properties of the container view:
var thisview = this; // required

this.validateControls = function(button)
{
    var textControl = bpmEventHelper.ui.getView("Text1", thisview);
    var selectControl =  thisview.ui.get("Select1");
    textControl.getValue(); // returns the value of the SPARK control in 
    this coach view with the ControlId "Text1"
    selectControl.getSelectedItem(); // returns the selected value in the 
    SPARK control in this coach view with the ControlId "Select1"
}
		
As a general example, to access a FirstName text view inside an Address view, address it by using the absolute address, as follows:
"/Address/FirstName" or "${Address}.ui.get('FirstName')"
In formulas
Views can be referenced in formulas using the following syntax:
  • ${FieldName} refers to the view whose control id = FieldName.
  • @{FieldName} refers to the value of the view whose control id = FieldName.
  • ${FieldName).getValue() and @{FieldName} are equivalent.

Non-addressable layout views

Views that are used purely for layout purposes must be omitted from an address. For example, you can address a FirstName view that's nested in a VerticalLayout view by using the /FirstName address, and not /VerticalLayout/FirstName.
Tip: To exclude a non-addressable custom container view from an address, set the following property to true in the load function of the custom view, in the inline JavaScript section, under Behavior:
this.constructor.prototype.IS_ADDRESS_INVISIBLE = true;

Addressable custom views

When you create a custom view that you want to be addressable, call the following function in the load method:
bpmEventHelper.ui.loadView(this)
If your custom view has a content box, call the following function instead:
bpmEventHelper.ui.loadContainer(this)
In the unload function of your view, call the appropriate function:
bpmEventHelper.ui.unloadView(this)
or
bpmEventHelper.ui.unloadContainer(this)

References to peer fields in tables

When you use formulas in a table, you can access the fields in the my row by using a syntax that has = after the field name. For example, say you have defined the Quantity (Integer), Cost (Decimal), and Total (Decimal) views in a table. You can specify the value of the Total view by using the following formula:
@{Quantity=} * @{Cost=}
Note that no data binding is necessary for the Total view, meaning that no total data field is necessary in the table.

Helper functions

You can use the helper functions getParent and getSibling within the bpmext.ui.View namespace as example. In the example, it is easy to get to the container view or peer view without knowing the entire hierarchy.

For example, say you have a container view named CV, which includes two views named Button1 and Button2. Assuming btn1View is the bpmext.ui.View object for Button1, you can get to CV by using btn1View.ui.get(“CV”) or btn1View.ui.getParent();. You can get to Button2 by using bt1View.ui.getSibling(“Button2”).