bpmext.ui
Contains general view and container helper functions
Methods:
getNearestValidationContainer()
Returns:
{com.ibm.bpm.coach.CoachView}
Gets the nearest container view on the validation stack
Example
| var valContainer = bpmext.ui.getNearestValidationContainer(); |
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" |
getCoachNGViewPath(null)
Returns:
{string}
null
| Name | Type | Default | Description |
{com.ibm.bpm.coach.CoachView} | view |
Example
| var myPath = bpmext.ui.getCoachNGViewPath(viewRef); |
getRequiredViews([onlyEmpty], [fromView], [includeDefaultVisibilityViews])
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. | |
| includeDefaultVisibilityViews | {boolean} | include views whose visibility is the "Same as parent". Adjusts based on the visibility of the parent view. |
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 |
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 |
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) |
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 |
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 ); |
executeEventHandlingFunction(view, eventName, argument)
Returns:
{object}
Executes an event handling function. If the event does not exist the returned value will always be true. When the event is an inline function it always returns true unless the implementation explicitly returns false. When the event calls a custom function the return value is the data returned from the 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 |
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())}); |
presetConfigOption(view, childViewControlId, configOptionName, configOptionValue)
Can preset value of configuration option of view during construction phase in Inline Javascript. Use in situations where you need to programmatically preset config option because it is loaded only once during load event handler.
| Name | Type | Default | Description |
| view | {com.ibm.bpm.coach.CoachView} | View instance of the view where this method is executed. | |
| childViewControlId | {string} | Control ID of direct design time child view on which the event is to be preset. | |
| configOptionName | {string} | Name of configuration option to be preset. | |
| configOptionValue | {string} | Value which is to be preset to the configuration option. |
Example
| bpmext.ui.presetConfigOption(this, "myTable", "pageSize", 15); // ... Excerpt from Inline JavaScript of a view |
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"); |
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); |
alert(title, text, style, [topic], timeout, id, data, iconSetting.showIcon, iconSetting.iconName)
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 | |
| style | {string} | The style to use for this alert. Used to generate the event name for the alert. | |
| topic | {string} | "" | The topic of the 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. | |
| iconSetting.showIcon | {boolean} | True indicates that showing the alert icon, false means not showing icons, undefined indicates remain the default setting (carbon theme restricted) | |
| iconSetting.iconName | {String} | Name of a carbon icon, applying only on one alert instance. If the value is not defined, then default value will be applied (carbon icon only) |
Example
| bpmext.ui.alert("My Alert", "An important event has occurred", "G","MyTopic",10000,"myID"); |
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", {}); } |
forEachViewSibling(view, callback, includeContainers)
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 | |
| includeContainers | {boolean} | an indication of whether to return sibling container views |
Example
| bpmext.ui.forEachViewSibling(repeatingItemView, function(v){{console.log(bpmext.ui.getViewPath(v) + " has value " + v.getData())}); |
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 |
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); |
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" |
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); |
presetEventHandler(view, childViewControlId, eventName, eventHandler)
Can preset event of view in events section during construction phase in Inline Javascript. Use in situations where you need to programmatically preset event because it is loaded only once during load event handler.
| Name | Type | Default | Description |
| view | {com.ibm.bpm.coach.CoachView} | View instance where this method is executed.
Note that property __fn_preset_handler_numericIndex (e.g. __fn_preset_handler_2) is set on the prototype of the view. | |
| childViewControlId | {string} | Control ID of direct design time child view on which the event is to be preset. | |
| eventName | {string} | Name of the event to be preset. | |
| eventHandler | {function} | Event handler function which is to be preset. |
Example
| // ... Excerpt from Inline JavaScript of a view
bpmext.ui.presetEventHandler(this, "myTable", "eventON_LOAD", function() { bpmext.log.info("On rows loaded event using presetEventHandler"); }); |
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 |
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); |
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. |
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); |
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"); |
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 |
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); |
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); |
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); |
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. |
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())}); |
getValidationContainers()
Returns:
{com.ibm.bpm.coach.CoachView[]}
Returns the validation container stack
Example
| var valContainers = bpmext.ui.getValidationContainers(refView); |
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); |
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. |
addViewValidationError(view, id, text)
Adds the error of 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 id of the validation error | |
| text | {string} | Validation error text to show on the invalid-styled view |
Example
| bpmext.ui.addViewValidationError(viewRef, "myErrorId", "Please fix your data entry"); |
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 |
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); |
publishEvent(eventName, payload, [persistent], [async])
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. |
| async | {boolean} | false | indicator of whether the subscribers should be notified asynchronously or not |
Example
| bpmext.ui.addEventSubscription("myEvent", { parm1:'val1', parm2,'val2' } ); |
updateViewValidationState(view, event)
Merges the current set of validation errors on the view with the errors identified in event.
| 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, {errors: [{message: "Error 1"}, {message: "Error 2"}]}); |
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); |
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); |
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. |
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) |
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); |