bpmext.ui
Contains general view and container helper functions
Methods:

getNearestValidationContainer() Returns: {com.ibm.bpm.coach.CoachView}
Gets the top view on the validation stack
Example
var valContainer = bpmext.ui.getNearestValidationContainer();

getFunctionContext(functionName, fromView) Returns: {Object}
Sometimes, event handlers in views need to call functions instead of using inline logic.
A function can be located in the view that fires the event, in an "ancestor" of the view, or at
the top level in a <script> section of the coach page. This function helps locate the named
function by starting at fromView and working up the ancestor chain. It stops as soon
as it finds a matching function in the closest ancestor to fromView.
NameTypeDefaultDescription
functionName{string}Name of the function to locate.
fromView{com.ibm.bpm.coach.CoachView}Reference to an SPARK
view/control from which to start the search.
Example
var res = bpmext.ui.getFunctionContext("myFunction", viewRef); res.fn(); // invoke the returned function

unloadContainer(view)
Deregisters a section Coach View (but not a regular view) from the view tree. Typically called in the unload event handler of the Coach View.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to a section-style SPARK view/control
Example
//Assumes unloadContainer is called in the unload handler of the Coach View
bpmext.ui.unloadContainer(this); //In this context "this" refers to the Coach View.

unloadView(view)
Deregisters a Coach View (but not a section) from the view tree. Typically called in the unload event handler of the Coach View.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control
Example
//Assumes unloadView is called in the unload handler of the Coach View
bpmext.ui.unloadView(this); //In this context "this" refers to the Coach View.

removeViewValidationError(view, id)
Removes the error on the specified id in the specified view
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}The view to be updated
id{string}The element id of the item to be marked
Example
bpmext.ui.removeViewValidationError(viewRef, valEvent);

publishEvent(eventName, payload, [persistent])
Publish an event.
NameTypeDefaultDescription
eventName{string}Name of the event to be published.
payload{object}to be passed to the registered callback function.
persistent{boolean}falseindicator of whether or not to make the publish persistent.
Example
bpmext.ui.addEventSubscription("myEvent", { parm1:'val1', parm2,'val2' } );

getContainer(viewPath, fromView) Returns: {com.ibm.bpm.coach.CoachView}
Retrieves the view corresponding to the path specified.
Note that the container path never contains section (e.g. Horizontal Section, etc...)
references other than for the last element of the path (which references the desired section).
NameTypeDefaultDescription
viewPath{string}Path is the format view/subview/subsubview/etc.
For arrays of view, use the [] notation. e.g. view/subview[0]/subsubview[5]/etc.
fromView{com.ibm.bpm.coach.CoachView}Optional reference to an SPARK
view/control from which to start the search. If not specified, search starts from the top of the view tree.
Example
var section1 = bpmext.ui.getContainer("view1/section1", myView);

getFunction(functionName, fromView) Returns: {function}
Sometimes, event handlers in views need to call functions instead of using inline logic.
A function can be located in the view that fires the event, in an "ancestor" of the view, or at
the top level in a <script> section of the coach page. This function helps locate the named
function by starting at fromView and working up the ancestor chain. It stops as soon
as it finds a matching function in the closest ancestor to fromView.
NameTypeDefaultDescription
functionName{string}Name of the function to locate.
fromView{com.ibm.bpm.coach.CoachView}Reference to an SPARK
view/control from which to start the search.
Example
var fn = bpmext.ui.getFunction("myFunction", viewRef);

pushValidationContainer(view)
Push the specified view into the validation container stack
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}The view to be pushed into the validation container stack
Example
bpmext.ui.pushValidationContainer(refView);

getContainerPath(view)
Returns the absolute path of the view/section (assumes the view was already initialized with bpmext.ui.loadContainer)
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK section (not a regular non-containing view)

substituteConfigOption(view, propertyName, defVal)
Low-level data management method to substitute a view configuration property
that is not set/undefined with a "pseudo" object that works like a real one. This helps simplify
code that would otherwise need to check if a config option is set of not (this method does nothing
if the option specified in propertyName is already set (i.e. view.context.options[propertyName] != undefined)
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control
propertyName{string}(Optional)
defVal{ANY}(Optional)
Example
bpmext.ui.substituteConfigOption(this, "showBorder"); //Assuming this method is called inside a view's load event

eventSubscriptionExists(eventName, view) Returns: {boolean}
Determine if a view is subscribing to an event.
NameTypeDefaultDescription
eventName{string}Name of the event to be checked.
view{com.ibm.bpm.coach.CoachView}Reference to the view to check.
Example
bpmext.ui.eventSubscriptionExists("myEvent", viewRef );

forEachViewSibling(view, callback)
Convenience iterator function. Calls the callback function for each of the view's identically named siblings
in a repeating view such as a Table, or Horizontal/Vertical layout. Each call to the callback function is
passed a reference to the view being iterated over, NOTE that this includes the specified view.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control
callback{function}function to be executed for each identically named sibling view
Example
bpmext.ui.forEachViewSibling(repeatingItemView, function(v){{console.log(bpmext.ui.getViewPath(v) + " has value " + v.getData())});

getChildContainers(view, [deep) Returns: {com.ibm.bpm.coach.CoachView[]}
Will return a list of all child container views of the specified view
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to a repeating SPARK view/control
[deep{boolean}= false] an indication of whether to drill down into nested views
Example
bpmext.ui.getChildContainers(repeatingItemView, function(v){{console.log(bpmext.ui.getViewPath(v) + " has value " + v.getData())});

getRequiredViews([onlyEmpty], [fromView]) Returns: {com.ibm.bpm.coach.CoachView[]}
Convenience method which finds all views in a tree that have visibility required, with the specified view as the root. If no root is specified, all views on page will be checked
NameTypeDefaultDescription
onlyEmpty{boolean}return only views that are required (visibility = REQUIRED) AND whose binding data is empty.
fromView{com.ibm.bpm.coach.CoachView}view to start the query from. Defaults to the page root.
Examples
var viewList = bpmext.ui.getRequiredViews(); //checks all views on the page and returns any whose visibility is REQUIRED
var viewList = bpmext.ui.getRequiredViews(true); //checks all views on the page and returns any whose visibility is REQUIRED and whose binding data is empty

setViewEnabled(enabled, required)
Enable/disable this view/control
NameTypeDefaultDescription
enabled{boolean}Enabled/read-only flag (true to enable view, false to disable/make read-only)
required{boolean}Enable/disable required flag for control
Example
bpmext.ui.setViewEnabled(viewRef,false); //Make MyView read-only

makeUniqueId(prefix) Returns: {string}
Returns a unique ID to be used on the currently-displayed page. The scope of the uniqueness in only the currently-displayed BPM Coach page.
NameTypeDefaultDescription
prefix{string|number}Optional prefix for ID
Example
//Could return A_12_78233 where A is the prefix, 12 is a numeric sequence, 78233 is a random number
var myId = bpmext.ui.makeUniqueId("A");

getView(viewPath, fromView) Returns: {com.ibm.bpm.coach.CoachView}
Retrieves the view corresponding to the path specified. Note that the view path never contains section
(e.g. Horizontal Section, etc...) references.
NameTypeDefaultDescription
viewPath{string}Path is the format view/subview/subsubview/etc.
For arrays of view, use the [] notation. e.g. view/subview[0]/subsubview[5]/etc.
fromView{com.ibm.bpm.coach.CoachView}Optional reference to an SPARK
view/control from which to start the search. If not specified, search starts from the top of the view tree.
Example
var subview1 = bpmext.ui.getView("view1/subview1", myView);

alert(title, text, [topic], colorStyle, timeout, id, data)
Broadcasts an alert withe the parameters specified
NameTypeDefaultDescription
title{string}The title of the alert
text{string}The text of the alert
topic{string}""The topic of the alert. Used to generate the event name for the alert.
colorStyle{string}The colorStyle to use for this alert. Used to generate the event name for the alert.
timeout{int}The timeout value in milliseconds. Time before the alert is removed.
id{string}The id of the alert.
data{object}The payload data for the alert.
Example
bpmext.ui.alert("My Alert", "An important event has occurred", "G","MyTopic",10000,"myID");

getViewPath(view)
Returns the absolute path of the view (assumes the view was already initialized with bpmext.ui.loadView)
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control (not a section)

getEventHandlingFunction(view, eventName) Returns: {function}
Retrieve an event handling function.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}Reference.
eventName{string}Name of the event handling function to be retrieved.
Example
bpmext.ui.getEventHandlingFunction(viewRef, "eventON_ROWSEL", "row"); // passes 1 additional argument "row"

getValidationContainers() Returns: {com.ibm.bpm.coach.CoachView[]}
Returns the validation container stack
Example
var valContainers = bpmext.ui.getValidationContainers(refView);

executeEventHandlingFunction(view, eventName, argument) Returns: {object}
Executes an event handling function.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}Reference.
eventName{string}Name of the event handling function to be executed.
argument{...object}Up to 9 arguments in addition to the view to pass to the function.
Example
bpmext.ui.executeEventHandlingFunction(viewRef, "eventON_ROWSEL", row); // passes 1 additional argument

getEffectiveVisibility(view)
returns the actual visibility of a view. Adjusts based on the visibility of the parent view.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control

getViewData(viewPath, fromView) Returns: {Object}
Retrieves the bound data for the view corresponding to the path specified.
Note that the view path never contains section (e.g. Horizontal Section, etc...) references.
NameTypeDefaultDescription
viewPath{string}Path is the format view/subview/subsubview/etc.
For arrays of view, use the [] notation. e.g. view/subview[0]/subsubview[5]/etc.
fromView{com.ibm.bpm.coach.CoachView}Optional reference to an SPARK
view/control from which to start the search. If not specified, search starts from the top of the view tree.
Example
var txt = bpmext.ui.getViewData("view1/Text1", myView);

getCoachNGViewPath(null) Returns: {string}
null
NameTypeDefaultDescription
{com.ibm.bpm.coach.CoachView}view
Example
var myPath = bpmext.ui.getCoachNGViewPath(viewRef);

getChildViews(view, [deep) Returns: {com.ibm.bpm.coach.CoachView[]}
Will return a list of all child views of the specified view
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to a repeating SPARK view/control
[deep{boolean}= false] an indication of whether to drill down into nested views
Example
bpmext.ui.getChildViews(repeatingItemView, function(v){{console.log(bpmext.ui.getViewPath(v) + " has value " + v.getData())});

updateViewValidationState(view, event)
Gets the top view on the validation stack
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}The view to be updated
event{object}The event passed to the validation event handler.
Example
bpmext.ui.updateViewValidationState(this, valEvent);

getOption(view, optionName, defaultValue) Returns: {ANY}
Retrieves the configuration option value - or the default value if the option is not set
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}Reference to a SPARK view/control
optionName{string}The name of the configuration option for the view
defaultValue{ANY}(Optional) The default value to return if the option is not set
Example
var prop1 = bpmext.ui.getOption(this, "prop1", "D"); //Return the value of .context.options.prop1, or "D" if .context.options.prop1 is not set

loadView(view)
Registers a Coach View (but not a section) as an SPARK view. Typically called in the
load event handler of the Coach View.
A view is not addressable through page.ui.get("/MyView1") or ${/MyView1} for example until loadView completes.


Note: Must never be called before calling bpmext.ui.setupFormulaTriggeredUpdates
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control
Example
//Assumes loadView is called in the load handler of the Coach View
bpmext.ui.loadView(this); //In this context "this" refers to the Coach View.

getInvalidViews([view]) Returns: {com.ibm.bpm.coach.CoachView[]}
Convenience method which checks the validity of all views in a tree (via the isValid() method), with the specified view as the root. If no root is specified, all views on page will be checked
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}view to start the check from. Defaults to the page root.
Examples
var invalidList = bpmext.ui.getInvalidViews(); //checks all views on the page and returns any marked as invalid
var invalidSection = bpmext.ui.getInvalidViews(${Horizontal_Layout1}); //checks all views inside Horizontal_Layout1

setViewData(data, viewPath, fromView) Returns: {Object}
Sets the bound data for the view corresponding to the path specified
NameTypeDefaultDescription
data{Object}The data to set into the view's bound data
viewPath{string}Path is the format view/subview/subsubview/etc.
For arrays of view, use the [] notation. e.g. view/subview[0]/subsubview[5]/etc.
fromView{com.ibm.bpm.coach.CoachView}Optional reference to an SPARK
view/control from which to start the search. If not specified, search starts from the top of the view tree.
Example
bpmext.ui.setViewData("TEST", "view1/Text1", myView);

removeEventSubscription(eventName, view)
Removes the specified event from the list of subscribed events for the specified view
NameTypeDefaultDescription
eventName{string}Name of the event to be removed.
view{com.ibm.bpm.coach.CoachView}Reference to an SPARK view/control which is subscribing.
Example
bpmext.ui.removeEventSubscription("myEvent", viewRef);

registerEventHandlingFunction(view, eventName, argument)
Register an event handling function.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}Reference to the view being processed.
eventName{string}Name of the event to be added.
argument{...object}Up to 9 arguments in addition to the view to pass to the function.
Example
bpmext.ui.registerEventHandlingFunction(viewRef, "eventON_ROWSEL", "row"); // passes 1 additional argument "row"

isViewExplicitlyLoaded(view) Returns: {boolean}
Returns an indication of whether or not this view has been explicitly loaded
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control
Example
var isSparkView = bpmext.ui.isViewExplicitlyLoaded(viewRef);

addEventSubscription(eventName, callback, view, [persistent])
Add an event subscription to a view.
NameTypeDefaultDescription
eventName{string}Name of the event to be subscribed to.
callback{function}function to receive control when the event is published.
view{com.ibm.bpm.coach.CoachView}Reference to an SPARK view/control which is subscribing.
persistent{boolean}falseindicator of whether or not to make the subscription persistent.
Example
bpmext.ui.addEventSubscription("myEvent", function{}, viewRef);

verifyEventHandlingFunctionRegistration(view, eventName)
Checks if an event handling function has been defined for this event. If an event is registered with no parameters.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}Reference.
eventName{string}Name of the event handling function to be executed.
Example
bpmext.ui.verifyEventHandlingFunctionRegistration(viewRef, "eventON_Change");

popValidationContainer(view)
Pop the specified view from the validation container stack
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}The view to be popped off the validation container stack
Example
bpmext.ui.popValidationContainer(refView);

substituteObject(view, type, propertyName, defVal)
Low-level data management method to substitute a view binding or a configuration property
that is not set/undefined with a "pseudo" object that works like a real one. This helps simplify
code that would otherwise need to check if a binding or config option is set of not
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to an SPARK view/control
type{string}(Optional) Specify "config" for a configuration object or "binding" for the bound object. Default is "binding" (if null is specified)
propertyName{string}When type is "config" specify the name of the configuration property, when type is "binding" specify the name of the "Business Data" variable (i.e. bound variable)
defVal{ANY}(Optional)
(e.g. "selectedItem" for the Select control)
Example
if(!this.context.binding) { //Assuming in load event of a coach view
this.context.binding = bpmext.ui.substituteObject(this);
this.context.binding.setQuiet("value", {});
}

loadContainer(view)
Registers a section Coach View (but not a regular view) as an SPARK view/section. Typically called in the
load event handler of the Coach View.
A view is not addressable through page.ui.get("/MySection1") or ${/MySection1} for example until loadContainer completes.
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}A reference to a section-style SPARK view/control
Example
//Assumes loadContainer is called in the load handler of the Coach View
bpmext.ui.loadContainer(this); //In this context "this" refers to the Coach View.

setupFormulaTriggeredUpdates(null, function, function)
Registers formula triggers for the specified view
NameTypeDefaultDescription
{com.ibm.bpm.coach.CoachView}view
function{function}The function to be called on update
function{function}The function to be called to get default values
Example
bpmext.ui.setupFormulaTriggeredUpdates(vieRef);

getViewValidationErrors(view) Returns: {string[]}
Returns the validation errors for the specified view
NameTypeDefaultDescription
view{com.ibm.bpm.coach.CoachView}The view who's errors are to be returned
Example
bpmext.ui.getViewValidationErrors(viewRef);