Client-Side Eventing

Publish-Subscribe Mechanism

The publish-subscribe eventing mechanism is implemented as a multicast service, which defines a one-to-many relationship between an event publisher and multiple event subscribers. A portal component that needs to publish certain notification and/or data, can raise an appropriate event and pass data along with this event. A component that needs to receive this notification and/or data, has to subscribe to the corresponding event and assign it to a handler.

The following code samples illustrate:

• Publishing an event:

  EPCM.raiseEvent("urn:com.sap.portal:testApp","test","anydata","mySender");

• Subscribing to an event:

  function myHandler( eventObject ){
  // eventObject.eventNamespace  ->returns  "urn:com.sap.portal:testApp"
  // eventObject.eventName       ->returns  "test" 
  // eventObject.dataObject      ->returns  "anydata"
  // eventObject.sourceId        ->returns  "mySender"
  }
  EPCM.subscribeEvent("urn:com.sap.portal:testApp", "test", myHandler ); 
  
                    

Event Subscription Options

Subscribing to an event requires passing information about the event handler to call whenever the event is triggered. The EPCF supports three different options for specifying an event handler by providing the following EPCM.subscribeEvent method signatures:

• Function reference

  The reference to an existing function is passed. This is the standard way recommended for Java portal components and suitable for most cases.

  function myHandler(eventObject) { /* some action  */}
  EPCM.subscribeEvent("urn:com.sap.portal:testApp", "test", myHandler ); 
  
                    

• Object and method name

  In this object-oriented approach, an event handler is defined as the method of a JavaScript object. Here the event handler is specified by a combination of the object reference and method name passed as a string value.

  myObject = new Object()
  myObject.myMethod = function(eventObject) { /* some action */} 
  EPCM.subscribeEvent("urn:com.sap.portal:testApp", "test", myObject, "myMethod"); 
  
                    

• Function name

  The name of any existing function is passed as a string value. When it is used, the framework stores internally the frame name obtained from the window reference and the function name.

  function myHandler(eventObject) { /* some action  */}
   EPCM.subscribeEvent("urn:com.sap.portal:testApp", "test", window, "myHandler"); 
  
                    

Reliable Eventing and Event Caching

If several components are rendered in their own frames on the same page, the content in each frame is loaded asynchronously. Thus, an event publisher may be loaded and ready to use before an event subscriber has registered its event handlers. In this case, the subscriber does not receive the publisher's events raised by the raiseEvent method, which means the delivery of the events is not reliable.

The EPCF provides a solution for this issue. Each event raised by raiseEvent is not only delivered to all currently available subscribers, but also cached in the internal event history table. The alternative subscribeEventReliable method not only subscribes the event handler for the future events, but also calls the event handler when the corresponding entry is found in the event history table. The available signatures of this method, parallel to those of subscribeEvent, are as follows:

•  EPCM.subscribeEventReliable("urn:com.sap.portal:testApp", "test", myHandler ); 
•       EPCM.subscribeEventReliable("urn:com.sap.portal:testApp", "test", myObject, "myMethod"); 
•       EPCM.subscribeEventReliable("urn:com.sap.portal:testApp", "test", window, "myHandler"); 

            

For details, see the Event Subscription Options section above.

Unsubscribing from Events

You can unsubscribe from events using the unsubscribeEvent method:

EPCM.unsubscribeEvent ( namespace, name, listenerId );

The listenerId parameter is required to identify an existing subscription. The namespace and name parameters are not enough to identify the subscription, because multiple handlers can be subscribed to the same namespace and name.

When you subscribe to an event with EPCM.subscribeEvent, store the returned value for later use.

function myHandler(){ alert("Hello World")}
var myId = EPCM.subscribeEvent( namespace, name, myHandler);
. . . 
EPCM.unsubscribeEvent(namespace,name,myID);

            

In cases where the JavaScript code is generated on the server side, you might want to generate listenerId in advance and pass it as an extra parameter for the event subscription. To avoid conflicts with other applications, make sure listenerId is unique. We recommend to include in listenerId the component name or even application namespace, as in the following example:

function myHandler(){ alert("Hello World")}
EPCM.subscribeEvent( namespace, name, myHandler, myID);. . . 
EPCM.unsubscribeEvent(namespace,name, myID);

            

Subscribing to All Events in a Namespace

To subscribe to all events in a given namespace, use the wildcard symbol * (asterisk) instead of an event name. However, this wildcard is accepted only in the subscribing and unsubscribing methods, you cannot use it to raise events.

function myHandler(eventObject) { /* some action  */}
EPCM.subscribeEvent("urn:com.sap.portal:testApp", "*", myHandler );

            

Subscribing to Browser Events

In many cases, portal components need to perform certain initialization tasks after loading into the browser. Since there can be several embedded iViews on the same page, the components cannot subscribe their handlers directly to the browser events in the <BODY window.onload=""> tag. In this case the event is delivered only to the latest subscribed component and only the last subscribed handler is called.

EPCF provides special browser events to which each component can subscribe:

Portal-Specific Events

The portal framework uses events as well. A restricted set of portal events is available as a public API, such as user logoff:

namespace: urn:com.sapportals.portal:user, name: logoff