Webex Connect: Exploiting The Event Model Developer Technical Note

WebEx Connect: Exploiting the Event Model Developer Technical Note

WebEx Communications Inc. 3979 Freedom Circle, Santa Clara, CA 95054 Corp: +1-408-435-7000 Sales: +1.877.50.WEBEX www.webex.com

WebEx Communications, Inc.

Introduction The WebEx Connect™ Integration Platform offers a flexible and robust means for integrating customer and partner applications. The central integration mechanism is the construction of WebEx Connect Applications that surface application functionality and content into the WebEx Connect Client. One major thing that differentiates the WebEx Connect Application Framework from other Web 2.0 platforms is the Event Model. This Tech Note will explore the interfaces for working with events, and provide concrete examples of what the event model can do for you. This Tech Note assumes the reader has a reasonable familiarity with the overall WebEx Connect Platform, as can be found in the WebEx Connect Technical Overview white paper available on the Connect Developer Community site, under Resources. http://community.webex.com/connect.

The Application Framework The Application Framework provides the environment for running Widgets in WebEx Connect Spaces. The framework provides the overall definition of Application Modules, a run-time environment, and a set of APIs that allow the App Module to interact with the Connect client environment as well as other Modules.

Framework APIs The Application framework provides full life-cycle management, configuration parameter management, and a set of calls that enable the App Module to interact with external services and with the environment. A full description of the Application framework is available in the WebEx Connect Application Framework reference guide, available in the Connect Developer Community. The focus of this Tech Note is on the event-related APIs of the framework. A Connect Application contains a high level App Module that is broken into three basic parts, View, Store, and Wire. This construct is based on the classic Model, View, Controller programming paradigm (MVC). The Event model is part of a specific Store (the WbxClientAPIStore), and is not to be confused with the concept of Wires that link trigger events from View modules to activities and data transfers to other modules. Events encompass both life-cycle events (Init, Start, Stop, Terminate), built-in events emanating from the platform (notifications, etc.), and custom events.

Event APIs Application Modules can subscribe to all the events generated in the system and publish their own events. The framework provides a number of built-in events, such as incoming life-cycle, IMs, people entering or leaving a Space, a Buddy coming on line, etc. The App Module infrastructure provides APIs to publish/subscribe to both built-in and custom events as methods of the WbxClientAPIStore: ‰ mashkit.data.WbxClientAPIStore.subscribe(): this method allows an App Module to subscribe to a known event. The event can either be a built-in platform event, or a custom event originating from some other Module that is known. When subscribing, the caller provides a call-back function that is invoked when the event occurs, and this call-back is responsible for processing the event data. A Module can also un-subscribe to an event using mashkit.data. WbxClientAPIStore.unsubscribe(). ‰ mashkit.data.WbxClientAPIStore.publish(): this container call enables a Module to publish its own custom events. The Module can provide its own event name/topic, scoped by the Module’s own namespace, and can pass any data desired as the event message. These calls specify an “event node” as an argument, which is essentially the name or “topic” of the event of interest. Event nodes are a hierarchical tree structure (as are most things in Connect) that allow the caller to access, and extend, the event model. When events are published, they contain a

Exploiting the Widget Event Model

2

5/7/2008

WebEx Communications, Inc.

“message” to the recipient. This can be a simple string, or a complex JavaScript object. It is the responsibility of the subscriber to not only know the event name, but also know how to parse the message. The underlying JavaScript framework intercepts events and bubbles them through an event filter to dispatch them to the appropriate Module(s). Modules must subscribe to events of interest in order to receive a notice of the event. Events without a subscriber are ignored.

Life-Cycle Events As the Application runs inside a connect UI container, this container controls the lifecycle of the application. Whenever the stage in the life cycle changes, the container sends an event to the application. These events are always sent in sequence init, start, stop and terminate • • • •

init The application should subscribe for this event if it needs to initialize the some part of the application or some data. The container will send this event after it has initialized itself. start This event is sent when container is ready for rendering. Applications can start rendering themselves when they get this event. stop When the application is out of focus, this event is sent terminate When the container is being closed, this event is sent out to all applications to clean up and close themselves.

Subscribing to Life-Cycle Events Any lifecycle event that the application wants to subscribe to has to be mentioned in the header section of the App Construct.

…….. <events>init <events>start <events>stop <events>terminate ……..

An application can choose to either subscribe for all the lifecycle events, or only the ones it needs. The events described in the header are accessible by using $(root).<event> in the code of the application. The example below shows how to call a sayHello function on a start event and a sayBye function on a stop event. onStart mashkit.wire.Invocation <params> $(root) start <method>sayHello onStop

Exploiting the Widget Event Model

3

5/7/2008

WebEx Communications, Inc.

mashkit.wire.Invocation <params> $(root) stop <method>sayBye

Custom Events Custom events allow Modules to create their own interaction mechanisms. Events can be published and subscribed across different Applications with in the Space, in the same client or across different clients. When event are across clients, the framework uses the Connect Platform Services (CPS) notification service. Otherwise, it just uses the underling Dojo event mechanism. Any event topic names starting with /server/ are server events/notifications. They are sent to the CPS backend to be distributed to other clients listening on the same topic. Otherwise, the event will be local to client and workspace.

Event Publishing Events can be published and subscribed across different Applications with in the Space, in the same client or across different clients. When event are across clients, the framework uses the Connect Platform Services (CPS) notification service. Otherwise, it just uses the underling Dojo event mechanism. Any event topic names starting with /server/ are server events/notifications. They are sent to the CPS backend to be distributed to other clients listening on the same topic. Otherwise, the event will be local to client and workspace.

Event Subscription Event subscription has a similar format with the addition that the subscription also involves implementing an event handler. The event handler is passed the event data, so the handler methods should be declared with the event data as arguments.

Example The example code snippet below illustrates subscribing to and publishing a local event, and subscribing to and publishing a server event: var clientapiStore = new mashkit.data.WbxClientApiStore.getInstance(); //Subscribe for Local event var topicName="/my/topic/name"; clientapiStore.subscribe(topicName,this, "myListener"); //Publish Local event topicName="/my/topic/name"; var somedata=[ "read this", "hello world"]; clientapiStore.publish(topicName,somedate); //Subscribe server side (across clients) events var channelName= "/server/connect/notification/W6U5K6AY0I1V745C6MN9JN9C19"; clientapiStore.subscribe(channelName,this,

Exploiting the Widget Event Model

4

5/7/2008

WebEx Communications, Inc.

"myServerListener"); //Publish events across clients channelName= "/server/connect/notification/W6U5K6AY0I1V745C6MN9JN9C19"; var message={ test: "cometd Test Data" }; clientapiStore.publish(channelName,message);

Conclusion The WebEx Connect Application Framework enables a new class of application integration by allowing App Modules to interact and cooperate using the event model. This capability enables you to construct sets of cooperating modules that not only capture and process various real-time events that occur in the WebEx Connect platform, but also is fundamentally extensible so that your modules can synchronize their operations and provide a rich, contextually-relevant experience to end users.

©2008 WebEx Communications, Inc. WebEx, WebEx MediaTone, and the WebEx logo are registered trademarks of WebEx Communications, Inc. All rights reserved. All other trademarks are the property of their respective owners.

Exploiting the Widget Event Model

5

5/7/2008