com.ibm.mashups.iwidget.services
Interface EventService


public EventService

This interface defines iWidget EventService which provides a topic driven subscribe/publish mechanism. "fireEvent" and "broadcastEvent" are provided as convenience functions on top of this basic model. The service can be retrieved using the following code:
var eventService = com.ibm.mashups.services.ServiceManager.getService(
    com.ibm.mashups.iwidget.services.EventService.SERVICE_NAME);


Field Summary
 String SERVICE_NAME
           The service name to be used to fetch the service from the ServiceManager
 
Method Summary
 void fireEvent(String targetWidget, String targetEvent, Object payload, String payloadType, String sourceid)
           Allows page component to invoke a handled event that's defined in an iWidget.
 void broadcastEvent(String targetEvent, Object payload, String payloadType, String sourceid)
           Allows page components to broadcast an event to all the widgets/components on the page.
 void broadcastEvent(String targetEvent, Object payload, String payloadType, String sourceid, String pageid)
           Allows page components to switch to a different page and broadcast an event to all the widgets/components on that page.
 void broadcastEvent(String targetEvent, Object payload, String payloadType, String sourceid, String pageid, String spaceid)
           Allows page components to switch to a different page and space and broadcast an event to all the widgets/components on that page.
 void broadcastEvents(Array eventsArray, String sourceid)
           Allows page components to broadcast more than one event to all the widgets/components on the page.
 void broadcastEvents(Array eventsArray, String sourceid, String pageid)
           Allows page components to switch to a different page and broadcast more than one event to all the widgets/components on that page.
 void broadcastEvents(Array eventsArray, String sourceid, String pageid, String spaceid)
           Allows page components to switch to a different page and space and broadcast more than one event to all the widgets/components on that page.
 void publishEvent(String topic, Object payload, String payloadType, String sourceid)
           Allows page component to publish a global event that's available to all the other page components.
 void subscribeEvent(String event, Object object, String eventCallback, String subscribeCallback, String sourceid)
           Allows page component to subscribe a global event that's available to all the other page components.
 void unsubscribeEvent(Object subscriptionHandler, String sourceid)
           Allows page component to unsubscribe a global event that's available to all the other page components.
 

Field Detail

SERVICE_NAME

String SERVICE_NAME
The service name to be used to fetch the service from the ServiceManager

Method Detail

fireEvent

void fireEvent(String targetWidget,
               String targetEvent,
               Object payload,
               String payloadType,
               String sourceid)
Allows page component to invoke a handled event that's defined in an iWidget.
For example, in Lotus Mashups, user can click "save" to save the attributes when user finished editing a widget .
Then the component that renders the "save" button could use this api to distribute an onModeChanged event to the widget.
     com.ibm.mashups.services.ServiceManager.getService("eventService").fireEvent(this.iwidgetId,"onModeChanged", { newMode:"view"});
So the widget could get notified and go back to "view"mode.
Same function can also be achieved by using "publishEvent"
     com.ibm.mashups.services.ServiceManager.getService("eventService").publishEvent("widgetevents."+this.iwidgetId+"."+"onModeChanged", { newMode:"view"});

Parameters:
targetWidget - id of target iWidget. Must never be NULL.
targetEvent - event name of target Event .Must never be NULL.
payload - optional. data object that's distributed with an event. May be NULL.
payloadType - optional. type of the payload
sourceid - optional. id of source component that triggers this event

broadcastEvent

void broadcastEvent(String targetEvent,
                    Object payload,
                    String payloadType,
                    String sourceid)
Allows page components to broadcast an event to all the widgets/components on the page. There's no need for widgets to subscribe that topic first.
For example, mode selector iWidget may broadcast a "pageModeChanged" event when page mode is changed from view mode to edit mode.
Then all the widgets/components will get notified and all widgets/components that can handle "pageModeChanged" event will update accordingly.
A widget that can handle this event must have this event defined.
      <iw:event id="pageModechanged" eventDescName="pageModeChanged_desc" handled="true" onEvent="handlePageModeChange" />
A component that can handle this event must subscribe this event by using:
      serviceManager.getService("eventService").subscribeEvent ("pageModechanged",handlerFn,scope,sourceid)
Code example:
     com.ibm.mashups.services.ServiceManager.getService("eventService").broadcastEvent("pageModeChanged", payload,payloadtype,,sourceid);
Same function can also be achieved by using "publishEvent"
     com.ibm.mashups.services.ServiceManager.getService("eventService").publishEvent("*"+"."+"onModeChanged", { newMode:"view"});

Parameters:
targetEvent - event name of target Event .Must never be NULL.
payload - optional. data object that's distributed with an event. May be NULL.
payloadType - optional. type of the payload
sourceid - optional. id of client component that triggers this event.

broadcastEvent

void broadcastEvent(String targetEvent,
                    Object payload,
                    String payloadType,
                    String sourceid,
                    String pageid)
Allows page components to switch to a different page and broadcast an event to all the widgets/components on that page.

Parameters:
targetEvent - event name of target Event .Must never be NULL.
payload - optional. data object that's distributed with an event. May be NULL.
payloadType - optional. type of the payload
sourceid - optional. id of client component that triggers this event.
pageid - optional. id of page to switch to and receive the event. If none is provided, no page switch will occur and event will broadcast to current page.

broadcastEvent

void broadcastEvent(String targetEvent,
                    Object payload,
                    String payloadType,
                    String sourceid,
                    String pageid,
                    String spaceid)
Allows page components to switch to a different page and space and broadcast an event to all the widgets/components on that page.

Parameters:
targetEvent - event name of target Event .Must never be NULL.
payload - optional. data object that's distributed with an event. May be NULL.
payloadType - optional. type of the payload
sourceid - optional. id of client component that triggers this event.
pageid - optional. id of page to switch to and receive the event. If none is provided, no page switch will occur and event will broadcast to current page.
spaceid - optional. id of space containing the page to switch to and receive the event. If none is provided, current space is assumed.

broadcastEvents

void broadcastEvents(Array eventsArray,
                     String sourceid)
Allows page components to broadcast more than one event to all the widgets/components on the page.

Parameters:
eventsArray - Array of objects each containing the following event information: { "targetEvent": targetEvent, "payload": payload, "payloadType": payloadType }. Must never be NULL.
sourceid - optional. id of client component that triggers this event.

broadcastEvents

void broadcastEvents(Array eventsArray,
                     String sourceid,
                     String pageid)
Allows page components to switch to a different page and broadcast more than one event to all the widgets/components on that page.

Parameters:
eventsArray - Array of objects each containing the following event information: { "targetEvent": targetEvent, "payload": payload, "payloadType": payloadType }. Must never be NULL.
sourceid - optional. id of client component that triggers this event.
pageid - optional. id of page to switch to and receive the events. If none is provided, no page switch will occur and events will broadcast to current page.

broadcastEvents

void broadcastEvents(Array eventsArray,
                     String sourceid,
                     String pageid,
                     String spaceid)
Allows page components to switch to a different page and space and broadcast more than one event to all the widgets/components on that page.

Parameters:
eventsArray - Array of objects each containing the following event information: { "targetEvent": targetEvent, "payload": payload, "payloadType": payloadType }. Must never be NULL.
sourceid - optional. id of client component that triggers this event.
pageid - optional. id of page to switch to and receive the events. If none is provided, no page switch will occur and events will broadcast to current page.
spaceid - optional. id of space containing the page to switch to and receive the events. If none is provided, current space is assumed.

publishEvent

void publishEvent(String topic,
                  Object payload,
                  String payloadType,
                  String sourceid)
Allows page component to publish a global event that's available to all the other page components.
Event service supports global topics. For these topics all the page components could subscribe to it.
For example. when an iWidget is removed from page, a global event -"/enabler/unloadWidget" will be published by the skin component.
iWidget container is a subscriber of this topic, thus it can clean up the resource related to this iWidget accordingly.

Parameters:
topic - topic that's published.Must never be NULL.
payload - optional. payload object.
payloadType - optional. type of the payload
sourceid - optional. id of client component that triggers this event.

subscribeEvent

void subscribeEvent(String event,
                    Object object,
                    String eventCallback,
                    String subscribeCallback,
                    String sourceid)
Allows page component to subscribe a global event that's available to all the other page components.
Event service supports global topic. for these topics all the page listeners could subscribe to it.
For example. when an iWidget is removed from page, a global event -"/enabler/unloadWidget" will be published by the skin component.
iWidget container is a subscriber of this topic, thus it can clean up the resource related to this iWidget accordingly.

Parameters:
event - event name
object - optional. scope object of the handlerFn. default scope is global scope.
eventCallback - optional. eventCallback that will be invoked when event is published
subscribeCallback - optional. callback to tell is subscription is good
sourceid - optional. id of client component that subscribes this event

unsubscribeEvent

void unsubscribeEvent(Object subscriptionHandler,
                      String sourceid)
Allows page component to unsubscribe a global event that's available to all the other page components.

Parameters:
subscriptionHandler - subscriptionHandler
sourceid - optional. id of client component that subscribes this event


Copyright IBM Corp. 2010 All Rights Reserved.