Events and subscribers

Screen behavior is governed by events such as click event for a push button or blur event for any text widget.

Events are categorized as follows:

UI events
UI events are related to widget and their lifecycle. For example, the onClick event is raised on clicking a push button and afterSrceenInit event is raised on initializing a screen. Generally, the format of all the UI event IDs are <uId of the widget>_<event name>. For example, if the uId of a widget is bCreate and the event is onClick, the UI event ID is bCreate_onClick.
Business events
Business events are used in the application to control business logic on a screen. Generally, business events are not associated to any UI widget.

Note: Both UI and Business event IDs are case-sensitive.

Both UI or Business events can contain subscribers that are associated with an event, which is called whenever the event is raised. Subscribers can be classified into global and local subscribers. Local subscribers are called only at the screen level. Therefore, when an event is raised, the local subscriber of the screen instance for which the event is raised is called. Global subscribers are called across screens. Therefore, when an event is raised, all the screen instances with a global subscriber for an event are called. The order of local subscribers is governed by the sequence number, but not for global subscribers. Therefore, global subscribers can be called in any order. You can use a sequence number only in the following ranges:

Range 11 - 19 - Use any sequence number in the range of 11 to 19 when you want to add a subscriber before an application-provided subscriber
Range 51 - 99: Use any sequence number in the range of 51 to 99 when you want to add a subscriber after an application-provided subscriber.

All the other sequence numbers are reserved. Therefore, ensure not to use them.

Note:

It is suggested that you do not define subscribers with the same sequence number. Otherwise, the subscribers might be randomly called.
The order and type of arguments that are received in local and global subscribers for an event differs.
The sequence in which the local or global subscribers are called might differ, if a subscriber is used to do any asynchronous task such as opening a new screen or wizard in an editor.
When you are defining subscribers for an event by using the IBM® Extensibility Workbench, you need not provide the sequence numbers as they are automatically generated based on whether you choose to add subscriber before or after an existing one.

The following scenarios describe the process of adding local subscribers to an event:

Add subscribers to an event after the application-provided subscriber

You can add a subscriber for the bCreate_onClick UI event after the application-provided subscriber with a sequence number in the range of 51 - 99. For example, if the application-provided subscriber definition is as follows:

subscribers: {
    local: [{
	eventId: 'bCreate_onClick',
	sequence: '25',
	handler: {
	    methodName: "createOrderAction"
	}
    }]
}

You can add a subscriber in the screen extension as follows:

subscribers: {
    local: [{
	eventId: 'bCreate_onClick',
	sequence: '51',
	handler: {
	    methodName: "extn_createOrderAction_after"
	}
    }]
}

Add subscribers to an event before the application-provided subscriber

You can add a subscriber for the bCreate_onClick UI event before the application-provided subscriber with a sequence number in the range of 11 - 19. For example, you can add a subscriber in the screen extension as follows:

subscribers: {
    local: [{
	eventId: 'bCreate_onClick',
	sequence: '19',
	handler: {
	    methodName: "extn_createOrderAction_before"
	}
    }]
}

Stop the execution of an application-provided subscriber for an event

To stop the execution of an application-provided subscriber, use the sc.plat.dojo.utils.EventUtils.stopEvent utility and add a subscriber before the application-provided subscriber.

Note:

The sc.plat.dojo.utils.EventUtils.stopEvent utility is applicable only for local subscribers.
If you do any asynchronous task such as opening a new screen or a wizard, use the sc.plat.dojo.utils.EventUtils.stopEvent utility before you do the task.

Add subscribers to an event that does not have an application-provided subscriber

To add a subscriber to an event that does not have an application-provided subscriber, use the subscriber sequence in the allowed range.

Note:

When you add a subscriber to an event in which the handler does some asynchronous operation such as Ajax request, the subsequent subscriber might not be called in the defined sequence.
The procedure to add subscribers to a UI or business event is the same. Only the event ID is different for each event.
By default, the subscriber definition is present in the local property. When you add a global subscriber to an event, the subscriber properties can be added under the global property of subscribers.
If you create a new screen, add the subscriber property in the <Screen>UI.js file. If you extend an existing screen, define or generate the subscriber property in the <ScreenExtension>UI.js file.
The handler can be a method that is defined in the screen extension or a utility method. If the handler is a utility method, the subscriber definition is as follows:
```
subscribers: {
    local: [{
	eventId: 'beforeEditorClosed',
	sequence: '25',
	handler: {
	    methodName: "handleEditorClose",
	    className: "UIUtils",
	    packageName: "ias.utils"
	}
    }],
}
```
Here, handler refers to ias.utils.UIUtils.handleEditorClose, a method handleEditorClose defined in the ias.utils.UIUtils utility.

For more information about event-related utility methods, see the JavaScript documentation.