Event API

The Event API provides a set of methods for communication between iViews on the client through a publish-subscribe mechanism. For background information, see Client-Side Eventing.

EPCM.subscribeEvent( nameSpace, eventName, eventHandler )

Subscribes an event handler to the specified event. Returns the event listener ID as a string.

The EPCF supports the different options to define the event handler in the event subscription by providing the following method signatures:

EPCM.subscribeEvent( nameSpace, eventName, eventHandler )

This method adds the event handler to the subscription list for the event defined by the nameSpace and the eventName parameters. The combination of nameSpace, eventName and eventHandler must be unique. It is not possible to subscribe the same event handler to several events.

For more information about names and namespaces, see Namespaces.

Parameters
Parameter	Type	Description
`nameSpace`	String	URN of the event namespace.
`eventName`	String	The event name you subscribe to. You can use an asterisk (*) to subscribe for all events of this namespace.
`eventHandler`	Function	Reference to the event handler.

Example Example

<script language ="JavaScript">
    function onWakeup( eventObj ) {
      alert( "got a wakeup call from " + 
             eventObj.sourceId + ": " + eventObj.dataObject );
    }
     ...
      EPCM.subscribeEvent( "urn:com.sap:alarmClock", 
                           "morningCall", onWakeup );
      ... 
      EPCM.subscribeEvent( "urn:com.sap:alarmClock", "*", onWakeup );
<script>

End of the code.

EPCM.subscribeEvent( nameSpace, eventName, objRef, methodName)

This method sets an object-method as an event handler for the specified event. The combination of nameSpace, eventName, objectReference and methodName must be unique.

Parameters
Parameter	Type	Description
nameSpace	String	URN of the event namespace
eventName	String	The event name you subscribe to. You can use an asterisk (*) to subscribe for all events of this name-space.
objRef	Object	Object reference to the event handler
methodName	String	Event handler method name as the member of the object

Example Example

<script language ="JavaScript">
    var myObject = {};
    myObject.onWakeup= function( eventObj ) {
      alert( "got a wakeup call from " + 
             eventObj.sourceId + ": " + eventObj.dataObject );
    }
     ...
     EPCM.subscribeEvent( "urn:com.sap:alarmClock", 
                           "morningCall", myObject,"onWakeup" );
      ... 
      EPCM.subscribeEvent( "urn:com.sap:alarmClock", "*",
                           "myObject,"onWakeup" );
<script>

End of the code.

EPCM.subscribeEvent( nameSpace, eventName, winRef, funcName)

This method subscribes a function within the specified frame/window as an event handler to the specified event. The combination of nameSpace, eventName, winRef and funcName must be unique.

Parameters
Parameter	Type	Description
`nameSpace`	String	URN of the event namespace
`eventName`	String	The event name you subscribe to. You can use an asterisk (*) to subscribe for all events of this name-space.
`winRef`	Window Reference	Reference to the window or frame that contains the function acting as the event handler
`funcName`	String	Name of the function that acts as the event handler

Example Example

<script language ="JavaScript">
    function onWakeup ( eventObj ) {
      alert( "got a wakeup call from " + 
             eventObj.sourceId + ": " + eventObj.dataObject );
    }
     ...
     EPCM.subscribeEvent( "urn:com.sap:alarmClock", 
                           "morningCall", window, "onWakeup" );
      ... 
      EPCM.subscribeEvent( "urn:com.sap:alarmClock", "*",
                           Window ,"onWakeup" );
<script>

End of the code.

EPCM.subscribeEventReliable()

This method subscribes an event handler to the specified event, ensuring the reliable delivery of the event. For background information, see Client-Side Eventing → Reliable Eventing.

The available signatures of this method, parallel to those of EPCM.subscribeEvent, are as follows:

EPCM.subscribeEventReliable( nameSpace, eventName, eventHandler )

EPCM.subscribeEventReliable( nameSpace, eventName, objRef, methodName)

EPCM.subscribeEventReliable( nameSpace, eventName, winRef, funcName)

EPCM.unsubscribeEvent ( nameSpace, eventName,listenerId)

Unsubscribes the event handler specified by nameSpace, eventName and listenerId, which is returned by the subscription method.

Parameters
Parameter	Type	Description
`nameSpace`	String	URN of the event namespace
`eventName`	String	The event name with which the event is raised
`listenerId`	String	Listener ID returned by the subscription method

Example Example

<script language ="JavaScript">
    function onWakeup( eventObj ) { /* */ }
    ...
    var listenerId =
        EPCM.subscribeEvent( "urn:com.sap:alarmClock", 
                             "morningCall", onWakeup );
      ... 
    EPCM.unsubscribeEvent( "urn:com.sap:alarmClock",
                           "morningCall", listenerId);
<script>

End of the code.

EPCM.raiseEvent( nameSpace, eventName, dataObject [, sourceId])

Raises the event defined by nameSpace and eventName. The EPCF service calls all event handlers, which are registered for this event, and passes the event object to the event handler.

The event object is created by the EPCF service whenever an event is raised. It combines the dataObject, the eventName and the sourceId (which may be null) parameters into a single argument for the event handler.

Parameter Description
Parameter	Type	Description
`nameSpace`	String	URN of the event namespace.
`eventName`	String	The name of the event to be raised
`dataObject`	Object	An object (string, number, boolean, or object) that contains a description of the event
`sourceId` `(optional)`	String	The component ID of the event source, for example, the ID defined at design-time. Specify `Null` or no parameter if you do not need the ID.

Example Example

<SCRIPT language ="JavaScript">
    ...
    EPCM.raiseEvent( "urn:com.sap:alarmClock", "morningCall", 
           "Good morning ladies and gentlemen", "iView_0815" );
    ... 
<SCRIPT>

End of the code.

Raising Events from Child Window in Parent Window

You can use the Event API to indirectly raise events from a child window in a parent window that opened it.

To raise an event from a child window in its parent window:

In the parent window, subscribe to an event in a namespace, for example, MyNewNamespace:
EPCM.subscribe("MyNewNamespace","RefreshInbox", eventHandler);
In the child window, raise the event with the urn:com.sapportals.portal:childToParents namespace, and the event name, which is a concatenation of the namespace (MyNewNamespace) and name of the event to which the parent window is subscribed (RefreshInbox), joined by &:
EPCM.raiseEvent("urn:com.sapportals.portal:childToParents", "MyNewNamespace&RefreshInbox");

Note

If child windows are opened in a sequence, the event is passed through all the windows in this sequence, but the specified event handler is executed only in the windows that are subscribed to this event.

End of the note.