Namespace: ui

bpmext. ui

ui namespace containing instance convenience functions

Classes

View

Methods

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 optional indicator of whether or not to make the subscription persistent.
Example
bpmext.ui.addEventSubscription("myEvent", function{}, viewRef);

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 "" optional 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 alret.
data object The payload data for the alert.
Example
bpmext.ui.alert("My Alert", "An important event has occurred", "G","MyTopic",10000,"myID");

eventSubscriptionExists(eventName, view){boolean}

Determine if a view is subscribing to an event.
Name Type Description
eventName string Name of the event to be checked.
view com.ibm.bpm.coach.CoachView Reference to the view to check.
Returns:
Type Description
boolean True if the specified event is subscribed to by the specified view. False otherwise.
Example
bpmext.ui.eventSubscriptionExists("myEvent", viewRef );

executeEventHandlingFunction(view, eventName, argument){object}

Executes an event handling function.
Name Type Description
view com.ibm.bpm.coach.CoachView Reference.
eventName string Name of the event handling function to be executed.
argument object repeatable Up to 9 arguments in addition to the view to pass to the function.
Returns:
Type Description
object result. The return data from the specified event handling function.
Example
bpmext.ui.executeEventHandlingFunction(viewRef, "eventON_ROWSEL", row); // passes 1 additional argument
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.
Name Type 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())});
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 optional an indication of whether to drill down into nested views
Returns:
Type Description
Array.<com.ibm.bpm.coach.CoachView> An array of coach views
Example
bpmext.ui.getChildContainers(repeatingItemView, function(v){{console.log(bpmext.ui.getViewPath(v) + " has value " + v.getData())});
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 optional an indication of whether to drill down into nested views
Returns:
Type Description
Array.<com.ibm.bpm.coach.CoachView> An array of coach views
Example
bpmext.ui.getChildViews(repeatingItemView, function(v){{console.log(bpmext.ui.getViewPath(v) + " has value " + v.getData())});
Name Type Description
view com.ibm.bpm.coach.CoachView
Returns:
Type Description
string A string representing the path of the specified view.
Example
var myPath = bpmext.ui.getCoachNGViewPath(viewRef);
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).
Name Type 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.
Returns:
Type Description
com.ibm.bpm.coach.CoachView
Example
var section1 = bpmext.ui.getContainer("view1/section1", myView);
Returns the absolute path of the view/section (assumes the view was already initialized with bpmext.ui.loadContainer)
Name Type Description
view com.ibm.bpm.coach.CoachView A reference to an SPARK section (not a regular non-containing view)
returns the actual visibility of a view. Adjusts based on the visibility of the parent view.
Name Type Description
view com.ibm.bpm.coach.CoachView A reference to an SPARK view/control

getEventHandlingFunction(view, eventName){function}

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

getFunction(functionName, fromView){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 atthe top level in a <script> section of the coach page. This function helps locate the namedfunction 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 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.
Deprecated
  • Use getFunctionContext instead
    Returns:
    Type Description
    function
    Example
    var fn = bpmext.ui.getFunction("myFunction", viewRef);

    getFunctionContext(functionName, fromView){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 atthe top level in a <script> section of the coach page. This function helps locate the namedfunction 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 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.
    Returns:
    Type Description
    Object with "fn" and "view" properties. "fn" is a reference to the function. "view" is the view containing the function or the window global object
    Example
    var res = bpmext.ui.getFunctionContext("myFunction", viewRef); res.fn(); // invoke the returned function
    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 Description
    view Object optional view to start the check from. Defaults to the page root.
    Returns:
    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
    Gets the top view on the validation stack
    Returns:
    Type Description
    com.ibm.bpm.coach.CoachView The current top of the validation container stack or null if the stack is empty
    Example
    var valContainer = bpmext.ui.getNearestValidationContainer();

    getOption(view, optionName, defaultValue){ANY}

    Retrieves the configuration option value - or the default value if the option is not set
    Name Type 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
    Returns:
    Type Description
    ANY The value of the option if set, or the default value if specified, otherwise undefined
    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

    getRequiredViews(onlyEmpty, fromView)

    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 Description
    onlyEmpty boolean optional return only views that are required (visibility = REQUIRED) AND whose binding data is empty.
    fromView Object optional view to start the query from. Defaults to the page root.
    Returns:
    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
    Returns the validation container stack
    Returns:
    Type Description
    Array.<com.ibm.bpm.coach.CoachView> An array of views from validation container stack
    Example
    var valContainers = bpmext.ui.getValidationContainers(refView);
    Retrieves the view corresponding to the path specified. Note that the view path never contains section (e.g. Horizontal Section, etc...) references.
    Name Type 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.
    Returns:
    Type Description
    com.ibm.bpm.coach.CoachView
    Example
    var subview1 = bpmext.ui.getView("view1/subview1", myView);

    getViewData(viewPath, fromView){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.
    Name Type 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.
    Returns:
    Type Description
    Object
    Example
    var txt = bpmext.ui.getViewData("view1/Text1", myView);
    Returns the absolute path of the view (assumes the view was already initialized with bpmext.ui.loadView)
    Name Type Description
    view com.ibm.bpm.coach.CoachView A reference to an SPARK view/control (not a section)

    getViewValidationErrors(view){Array.<string>}

    Returns the validation errors for the specified view
    Name Type Description
    view com.ibm.bpm.coach.CoachView The view who's errors are to be returned
    Returns:
    Type Description
    Array.<string> errors An array of errors for the specified view.
    Example
    bpmext.ui.getViewValidationErrors(viewRef);

    isViewExplicitlyLoaded(view){boolean}

    Returns an indication of whether or not this view has been explicitly loaded
    Name Type Description
    view com.ibm.bpm.coach.CoachView A reference to an SPARK view/control
    Returns:
    Type Description
    boolean True if the specified view is a SPARK view, false otherwise.
    Example
    var isSparkView = bpmext.ui.isViewExplicitlyLoaded(viewRef);
    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.
    Name Type 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.
    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
    Name Type 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.
    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 Description
    prefix string | number Optional prefix for ID
    Returns:
    Type Description
    string
    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");
    Pop the specified view from the validation container stack
    Name Type Description
    view com.ibm.bpm.coach.CoachView The view to be popped off the validation container stack
    Example
    bpmext.ui.popValidationContainer(refView);

    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 optional indicator of whether or not to make the publish persistent.
    Example
    bpmext.ui.addEventSubscription("myEvent", { parm1:'val1', parm2,'val2' } );
    Push the specified view into the validation container stack
    Name Type Description
    view com.ibm.bpm.coach.CoachView The view to be pushed into the validation container stack
    Example
    bpmext.ui.pushValidationContainer(refView);

    registerEventHandlingFunction(view, eventName, argument)

    Register an event handling function.
    Name Type Description
    view com.ibm.bpm.coach.CoachView Reference to the view being processed.
    eventName string Name of the event to be added.
    argument object repeatable 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"	

    removeEventSubscription(eventName, view)

    Removes the specified event from the list of subscribed events for the specified view
    Name Type 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);

    removeViewValidationError(view, id)

    Removes the error on the specified id in the specified view
    Name Type 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(view, function, function)

    Registers formula triggers for the specified view
    Name Type Description
    view com.ibm.bpm.coach.CoachView
    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);

    setViewData(data, viewPath, fromView){Object}

    Sets the bound data for the view corresponding to the path specified
    Name Type 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.
    Returns:
    Type Description
    Object
    Example
    bpmext.ui.setViewData("TEST", "view1/Text1", myView);
    Enable/disable this view/control
    Name Type 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

    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 simplifycode that would otherwise need to check if a config option is set of not (this method does nothingif the option specified in propertyName is already set (i.e. view.context.options[propertyName] != undefined)
    Name Type 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

    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 simplifycode that would otherwise need to check if a binding or config option is set of not
    Name Type 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", {});}
    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 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.
    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 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.

    updateViewValidationState(view, event)

    Gets the top view on the validation stack
    Name Type 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);