Syntax documentationEvent 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

  1. <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

  1. <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

  1. <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 EventingReliable 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

  1. <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

  1. <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:

  1. In the parent window, subscribe to an event in a namespace, for example, MyNewNamespace:

    EPCM.subscribe("MyNewNamespace","RefreshInbox", eventHandler);

  2. 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 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.