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
as it finds a matching function in the closest ancestor to
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.| Name | Type | Default | Description |
| 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.| Name | Type | Default | Description |
| 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.| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| eventName | {string} | Name of the event to be published. | |
| payload | {object} | to be passed to the registered callback function. | |
| persistent | {boolean} | false | indicator 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).
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).
| Name | Type | Default | Description |
| 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
as it finds a matching function in the closest ancestor to
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.| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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)
| Name | Type | Default | Description |
| 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)
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)
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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.
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.
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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.
(e.g. Horizontal Section, etc...) references.
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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)
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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.
Note that the view path never contains section (e.g. Horizontal Section, etc...) references.
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
{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
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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 |
loadView(view)
Registers a Coach View (but not a section) as an SPARK view. Typically called in the
A view is not addressable through
Note: Must never be called before calling
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| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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.
| Name | Type | Default | Description |
| 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} | false | indicator 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.
| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
| 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
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
| Name | Type | Default | Description |
| 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
A view is not addressable through
load event handler of the Coach View.
A view is not addressable through
page.ui.get("/MySection1") or ${/MySection1} for example until loadContainer completes.| Name | Type | Default | Description |
| 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
| Name | Type | Default | Description |
{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
| Name | Type | Default | Description |
| view | {com.ibm.bpm.coach.CoachView} | The view who's errors are to be returned |
Example
| bpmext.ui.getViewValidationErrors(viewRef); |