Control Addressing

Overview

One of the key benefits of using SPARK UI Toolkit (SPARK) is the ability to address every SPARK control defined on a page. This includes all SPARK controls even those which are nested within other coach views on the page.
NOTE: Standard IBM Coach Controls are not addressable under this addressing scheme.

The addressing scheme is a tree structure whose root is defined as "/" and is at the top of the page being displayed. Subsequent nodes in the tree are added as the page is loaded. There are two basic types of nodes:

1. Container
2. Element

Container nodes are nodes which can contain other nodes including elements, Coach Views, and other container nodes. The addressing scheme is similar to that used for a Directory.

The need to address SPARK controls arises most commonly in the functions which are called by SPARK control events and in the formulas which may be specified on some SPARK controls. Functions can be specified: inline; in a JavaScript script block of a Custom HTML control on the page; in the Inline JavaScript section of the behavior tab for a Coach View.

Addressing Styles

Relative and absolute addressing styles are supported. Starting a reference with "/" always implies an absolute reference (i.e. starting at the top of the view tree). Omitting the / at the beginning of the path always means "from where I am". Using ".." in a reference allows the reference to go back up a level - as a file directory tree would behave.

In a formula, the references are always computed from the "standpoint" of the field whose formula we are setting.

• Fields at the same level as the current one are simply referenced with the name of the field (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 as ../../FieldOneLevelAboveMe. Etc.
• Relative addressing using ../ can be convenient in some cases

Javascript methods to access controls

From a Custom HTML control

When you wish to access a control from a displayed page in a JavaScript block, the simplest way to do so is to use the page global control and its page.ui.get(ControlId path) method.
For example: assume I have a text control "Text1" and I wish to access it for validation purposes in a function being called from an onClick event of a button. The proper way to do so would be with code like the following:

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 Coach View

When you wish to access a control from a function contained in a coach view use one of the following:
bpmext.ui.getView(ControlId [, thisview])
thisview.ui.get(ControlId)
Note: thisview must be defined in the coach view. (See example below)
For example: assume I have defined a coach view with 2 controls "Text1" and "Select1" and I wish to access them for validation purposes in a function called validateControls being called from an onClick event of a button within the view. The proper way to do so would be with code like the following placed in the Inline javascript section on the Behavior tab of the coach view:

var thisview = this; // required

this.validateControls = function(button)
{
    var textControl = bpmext.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"
}
		

Controls can be referenced in formulas using the following syntax

• ${FieldName} refers to the view/control whose control id = FieldName
• @{FieldName} refers to the value of the view/control whose control id = FieldName
• ${FieldName).getValue() and @{FieldName} are equivalent

Referencing "peer" Fields in Tables

Within a table if you are using formulas you will likely need to access fields that are in "my" row. The syntax for this is to use an "=" after the field name.

For example: Suppose we have the following controls: Quantity (integer), Cost (decimal), and Total (decimal) specified in a table.
We can specify the value of the Total control using the following formula. Note The total control can be unbound, i.e. it is not necessary to have a total data field in the table.

			@{Quantity=} * @{Cost=}		 

Helper Functions

The JSDoc for helper functions can be found here.

An example of these helper functions is getParent and getSibling within the bpmext.ui.View namespace.

They make it easier for you to get at your parent or sibling without knowing the entire tree.

Let's say you are in a Coach View named CV and have Button1 and Button2.

Assuming btn1View is the bpmext.ui.View object for Button1, you could get to CV by doing btn1View.ui.get(“CV”) or by using btn1View.ui.getParent();  You could get to Button2 using bt1View.ui.getSibling(“Button2”).