The context object
The context object provides access to helper functions, such as a callback to fire a named boundary event.
Properties
Through the context object, you can access its properties.Property | Description |
---|---|
context.binding | Provides access to the data object that is bound
to the current view. To access the data, use the following call:
Where value is
a special property name that returns the bound data object.For
example, if a view is bound to local.phoneBook.title,
the view can get the title by using the following code:
|
context.contextRootMap | Contains the values of different context roots
of the IBM® BPM servers.
Use this API to construct the URL that your coach views use to connect
to these servers. The object has the following properties:
|
context.element | Contains the root DOM element of the coach view.
The view must not delete this DOM element. Views that are defined
in the layout are children of this root element. Generally, the view
uses this root DOM element to locate its own content. Note: Multiple
instances of the same view can be on the same HTML page. Use this
root DOM element to scope your search.
|
context.options | Provides access to the configuration options of the view. These configuration options include the properties that users can set for the view such as the label for a button control and metadata properties. |
context.subview[viewid] | Returns an object with the div ID
of the subview as a property name. In a non-repeating scenario, there
is usually only one property. Generally context.getSubview() is
a more convenient function to use.
For more information, see Example: Get and use a domNode and Example: Get a div ID.
|
context.bpm.system | Provides access to the following system values:
|
context.bpm.system.settings | Provides access to the following properties
related to timer-based refreshing for coach views:
|
context.bpm.team.manager | Lists the teams that the current user is manager
of. The list ("[]") is empty by default. Each item
in the list for context.bpm.team.manager is an object
that contains the following properties:
|
context.bpm.team.member | Lists the teams that the current user is member
of. The list ("[]") is empty by default. Each item
in the list for context.bpm.team.member is an object
that contains the following properties:
|
context.viewid | Contains the unique identifier for this view definition. Multiple view instances might have the same viewId. For more information, see context.getSubview(viewId, requiredOrder). |
Functions
Through the context object, you can access its functions.Function | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
context.bindingType() | Returns the type of the data binding. | ||||||||||
context.broadcastMessage(message) | Broadcasts the supplied message. Important: Do not use this API to send sensitive or confidential
information.
|
||||||||||
context.cancelBoundaryEvents() | Cancels the boundary events that have not been sent to server. If a callback function was supplied when the boundary event was triggered, the coach framework calls the callback function to update the status of the boundary event. For more information, see the context.trigger(callback) function. | ||||||||||
context.containDiffLoopingContext() | Returns a value of true if the following conditions
are true:
For example, the API returns a value of true for the following
structure:
The framework displays a message at run time when there is a mismatch in list lengths. For example, the message occurs for the previous example if ListA has four items and ListB has three items. For more information, see Data binding for coach views. You use containDiffLoopingContext() to, for example, determine whether to disable the add-and-delete capability of a table during the runtime even if a user specifies to enable the add-and-delete capability. Important: If the coach
view that contains a view-managed content box is bound to a list that
is not empty, do not call this API between deleting a domNode of
the content box and the rendering of the first repeating element.
The return value might not be accurate.
|
||||||||||
context.createView(domNode, index, parentView) | Creates a coach view instance and any subview
instances under the specified DOM element, which is usually a content
box div.
If domNode is the node of any view other than a content box, the framework creates a single instance of the view and returns it. If (domNode is the node of a context box, the framework creates view instances for all the views that are owned by the content box. The framework recursively creates views for all the framework-managed content boxes that are owned by the content box that is specified by the domNode parameter. The framework then returns an array of these view instances. The
following code snippet shows how to create a content box view.
For
more information, see Example: Get and use a domNode.
|
||||||||||
context.deleteView(domNode) | Deletes the coach view instance and any subview
instances, starting from the specified DOM element.
The following code snippet shows how to delete a view instance:
For
more information, see Example: Get and use a domNode.
|
||||||||||
context.getDomNode(uniqueViewId, optParam) | Returns the first match of the DOM node that
has its data-ibmbpm_uniqueViewId property that has
the specified ID or null if there is no match. The search starts with
the parent DOM node of the this.context.element unless
you pass in a different start node by using optParam.startNode and
the search checks only the immediate children of the start node unless
you pass in optParam.deepSearch=true.
|
||||||||||
context.getInheritedVisibility() | Returns a String containing the value of the visibility setting of the ancestors of the coach view that is calling this function. If visibility values of all of its ancestors are set to DEFAULT, the function returns EDITABLE. | ||||||||||
context.getOptions(viewDomNode) | Returns the options object for the coach view
given its viewDomNode. The options are returned even
when the view represented by viewDomNode is not yet
constructed. Typically, use this API in a view to look at the configuration
options (such as label or visibility ) of one of its child views before
it is created.
The following code snippet is an example of how you could use this API:
|
||||||||||
context.getStyle() | Returns the currently applied positioning information
specified in the Positioning properties of the coach designer. The
currently applied positioning is based on an inheritance model where
settings for larger screen width are applied to smaller screen sizes
if nothing is specified for the smaller screen sizes. If a given property
is not specified for any screen size, null is returned. The following
properties are defined:
|
||||||||||
context.getWL() | Returns the WL namespace if the coach view is running in an MobileFirst environment; otherwise null is returned. The WL namespace provides access to the MobileFirst API objects, methods, and constants. See Using IBM MobileFirst Platform Foundation to enable IBM BPM process applications in mobile environments | ||||||||||
context.bind(type, callbackFunc, scopeObject) | Registers a callback function to receive a change
notification associated with the specified type. For now, only thestyle type
is supported. Any other values will cause an exception to be thrown.
This setting change can be a design-time change in the positioning
settings or a change in the run-time screen size. Normally, the callback function invokes the context.getStyle() method to get the currently applied positioning. Only one notification
or callback is triggered even if more than one positioning property
is changed. This function returns an object that can be used to unregister
the callback. The returned object contains a unbind() method
that takes no parameter.
|
||||||||||
context.setGroupNotification() | When enabled, allows a coach view to receive notification of data binding and configuration option changes in a single notification for all changes within the current thread. The event object that is passed into the callback contains a single property type of value groupNotification. It does not have any information about the individual changes. Coach views should retrieve the latest binding and configuration option values after receiving the group notification. The following parameters are defined:
|
||||||||||
context.getSubview(viewId, requiredOrder) | Returns the subview instance given the subview
ID. This method is similar to context.subview[viewid] except
that the return value is an array of subview instances.
The call this.context.getSubview("viewid") returns an unsorted array of subview objects. The call this.context.getSubview("viewid", false) returns the same array. The only difference between the two calls and the function call this.context.getSubview("viewid", true) is that this.context.getSubview("viewid", true) returns an array of subview objects whose order matches the order of the DOM nodes in the DOM tree. For more information, see Accessing a child coach view by using a control ID. |
||||||||||
context.htmlEscape(text) | Escapes the specified text. This function is
used to avoid potential cross-site scripting (XSS) attacks.
|
||||||||||
context.isTrustedSite(origin) | Returns true if origin matches
the protocol, host, and port of the coach or a site listed on the
white list. For example, a coach view receives a postMessage event.
The coach view can check the origin of the event by calling this API
using event.origin as the parameter.
|
||||||||||
context.parentView() | Returns the parent view instance or null if there is no parent view. During the invocation of load(), the parentview object is created but not fully initialized. One reason it is not initialized is that load() of the parent view is called after the current load() function. Because the parentview object is not fully initialized, avoid calling this function in the load() function. | ||||||||||
context.refreshView() | Forces the coach view and all its subviews to rebind. As a result, the change() callback is called, which causes the view (and all its subviews) to refresh. | ||||||||||
context.setDisplay(isDisplay, domNode) | Shows or hides the specified DOM element by
removing or adding a CSS class that sets display:none.
When the domNode is hidden, the parent coach or coach
view does not reserve the space that domNode would
occupy.
|
||||||||||
context.setUniqueViewId(uniqueViewId, targetNode) | Sets the uniqueViewId in the data-ibmbpm_uniqueViewId property
of the targetNode. If the call does not include the targetNode,
this function sets the property for the DOM node of the this.context.element.
|
||||||||||
context.setVisibility(isVisible, domNode) | Shows or hides the specified DOM element by
removing or adding a CSS class that sets display:hidden.
When the domNode is hidden, the parent coach or coach
view reserves the space that domNode would occupy.
|
||||||||||
context.subscribeValidation() | Registers the coach view to receive the validation errors of descendant views that are bound to a different business object than the current view. These errors are contained in the errors_subscription list of the error event object. Views that do not have a data binding, such as the Tab stock control, can use this API to receive validation errors. | ||||||||||
context.trigger(callback, options) | Fires a named boundary event.
|
||||||||||
context.triggerCollaboration(payload) | Fires a custom collaboration event. The custom
message is sent to the browser of a collaborating user. The corresponding
view on the collaborating browser receives the collaboration() callback
with event.type = "custom".
|
||||||||||
context.unsubscribeValidation() | Unregisters the Coach View so that it no longer receives errors in the errors_subscription list. The view still receives the errors list if it exists. |
Example: Get and use a domNode
Many functions of the context object take a document node (domNode) as an argument. The following code example shows how to get a domNode and use it in a function.
1 var subview = this.context.getSubview("subviewID", "true")[5];
2 var subviewDomNode = subview.context.element;
3 this.context.deleteView(subviewDomNode);
- 1 The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the <div></<div> tag of the subview instance. The function getSubview(subViewID) returns an array of subviews. In this example, the intent is to get the sixth element in the index of arrays. The parameter true ensures that the objects of the array are returned in the same order as the DOM.
- 2 Get the domNode of the subview element that is returned in step 1.
- 3 Delete the subview by using the domNode that step 2 returns.
Example: Get a div ID
To get the div ID of an element, use the syntax this.context.element.id
To get the ID of a subview, first get the domNode of the subview and then use .id.
1 var subview = this.context.getSubview("subviewID", "true")[5];
2 var subviewDomNode = subview.context.element;
3 var subViewDomId = subviewDomNode.id; // This gives you the ID of the subview
- 1 The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the <div></<div> tag of the subview instance. The function getSubview(subViewID) returns an array of subviews. In our example, we want the sixth element in the index of arrays. The parameter true ensures that the objects of the array are returned in the same order as the DOM.
- 2 Get the domNode of the subview element that is returned in step 1.
- 3 Get the ID of the subview.