Many portal developers have used WebSphere Portal to create cooperative portlets that share events and data to enhance the user experience. For example, a selection submitted in one portlet could cause updated information to display in multiple related portlets, helping the portlets to stay synchronized in their presentation. This functionality is implemented on the server and relies on the portlets submitting action requests to the server so that it can perform the data transfers before the page is refreshed.
What is Dojo?
- Include the Dojo bootstrap.
- Identify the Dojo libraries your application requires. You use the
dojo.requirestatement to include the Dojo widget managing functions (
dojo.widget.*) and the Button widget (
The dojo.require statements specify the Dojo resources you are using in your application. The Dojo bootstrap will scan the page for these dojo.require statements and will dynamically include the corresponding libraries so that these resources are available. The dynamic loading process also handles all dependencies between Dojo libraries, so you only need to add
require statements for the resources you use directly.
Using Dojo with WebSphere Portal
Dojo’s unique loading strategy poses a challenge to portlet developers. The Dojo bootstrap,
dojo.js, should only be included once in an HTML page. Depending on the browser, having
dojo.js in your theme’s JSP, and to place the dojo.require statements in your theme and portlet JSP’s as required.
The conditional loader is contained in the file dojoLoader.jsp:
</script> in strings must be split; otherwise, some browsers will try to parse them as the actual start and end of a script. Modifying the theme JSP would be a much cleaner solution. Use this conditional loader technique only when you cannot modify the theme JSP.
Using Dojo events
Dojo includes an event communication system that enables developers to connect components of an application. This capability goes beyond the traditional DOM events of mapping events to any property, object, or element; it includes advanced features such as Aspect-Oriented Programming (AOP) or event publish/subscribe (pub/sub). This article focuses on the event pub/sub system, known as topics, and how you can use it for communication between portlets.
A summary of the dojo.event.topic API
dojo.event.topic.registerPublisher (String topic, Object obj, String funcName)
- Registers a function as a publisher on a topic. Any subsequent call to the function will cause an event to be published to the topic with the function’s arguments being passed on to any registered listeners for the topic.
dojo.event.topic.publish(String topic, Object message )
- Manually publishes the passed object to the specified topic. This object will then be passed to any registered listeners for the topic.
dojo.event.topic.subscribe(String topic, Object obj, String funcName)
- Subscribes the function to the specified topic. Any subsequent events published to the topic will create a function call for the subscribed function. A listener can subscribe to a topic at any time, even before the topic has been referenced by a publisher. Dojo creates the topic when it is first referenced by a subscriber or publisher.
dojo.event.topic.unsubscribe(String topic, Object obj, String funcName )
- Unsubscribes the function from the specified topic.
- Destroys the topic and un-registers all listeners of the topic.
dojo.event.topic.subscribe( "/myApp/myTopic", window, "myHandler");
This code would create a subscription to the topic
myHandler would be called with the published event passed as a parameter.
A working example
Let's explore a simple configuration with an event publisher portlet, two listener portlets, and a single topic. The published event object will contain two data fields that are consumed by the listener portlets. The sequence of events for communication between the portlets will be as follows:
Figure 1 Sample portlet event flow
- This handler uses the Dojo library to create an independent event object and to publish it to a topic. This new event is received by any topic subscribers without any connection to the original Publish Event button.
- The listener portlets contain topic subscription functions that are called by Dojo and which receive the event object. These functions update the portlet display with information contained in the event.
In the example the publisher portlet keeps a count of the number of times the Publish Event button has been clicked. The published event contains this count and a text message. Each of the listener portlets updates its display with one of the elements of the event message. Each time the listener portlets process an event, the updated area flashes to draw attention to the changes. This flash effect is not part of the event publish/subscription cycle; it has been added to improve the demonstration.
Event publisher portlet
Listing 1. Source for the event publisher portlet
Reading through the code, you see that the
dojoType tag identifies the
dojo.require statements identify the Dojo libraries that are used by this component. The call to dojo.addOnLoad() adds the
init function to the list of functions Dojo will call after the page DOM has finished loading. This technique is similar to setting a function in the window.onLoad handler except that Dojo handles having multiple
init function without having to worry about the
window.onLoad handler being overwritten.
<portlet:namespace> tag from the standard portlet tag library. This tag is replaced by an alpha-numeric string that is unique to the portlet instance which prevents namespace collisions when multiple portlets are assembled into a page. The
init function locates the
Publish Event button by its widgetId, and connects the onclick event of that widget to the event handler. The event handler increments the counter, constructs an event object, and uses the dojo.event.topic.publish API to publish the event object to the topic called myApp/myTopic. The event object has two elements:
count, the value of the counter
message, a text message containing the counter
Dojo will pass the event object to each of the event subscribers, which can then process the contents as they see fit.
Event subscriber portlet
The event subscriber portlet needs a display field which will be updated with information from the published event (when it arrives). The subscriber portlet also needs to register its event handling function for the topic. This registration is most conveniently done in an
Listing 2. Source for the event subscriber portlet
Similar to the event publisher portlet, the
dojo.require statements specify the Dojo libraries needed by this component, and dojo.addOnLoad registers the portlet’s
init function. The
init function creates a new event listener object and subscribes it to the topic called /myApp/myTopic by calling its load method. When an event is published to this topic, the handleEvent method of the listener object is called.The event handler locates the DOM element where the message count is displayed, and updates the element's HTML with the new value passed in the event object.
Then, the handler calls dojo.lfx.html.highlight() to create a visual highlight effect to draw the user’s attention to the updated area.
The sample application includes a second event subscriber portlet with the same basic functionality; it displays the event message instead of the count. Both listeners receive the same object from the event publication, but choose to work with different members of the object.
Running the example
Let's look at the sample application to see how these portlets work together.
- If you have not already done so download the sample Rational Application Developer 7 project interchange file which contains the portlets discussed in this article.
- Import the file into Application Developer.
- To deploy the portlets, either export a WAR file and deploy it in your WebSphere Portal, or run the portlets in the integrated test environment.
- Create a new test page and add all three portlets to this new page.
- To test the application, simply navigate to the test page you created in step 4 and click on the Publish Event button.
Each time you click the button, the page displays the two event listener portlets that flash and are updated with the count and the message that are published by the publisher portlet.
Figure 2. Sample portlets
Adding Ajax functionality to Web applications can greatly improve the user experience. In a WebSphere Portal environment, using Ajax in your portlets can come with the tradeoff of not having advanced functionality such as cooperative portlets. However, you can use the Dojo toolkit to add client-side interportlet communication. Portlet developers can use this technique to create dynamic, cooperative portlets that can stay synchronized while minimizing page refreshes and improving responsiveness.
|Code samples||dojoC2A.zip||1466 KB|
- Building Ajax portlets for WebSphere Portal
- The Dojo toolkit
- The Dojo event system
- Dojo event topics
- developerWorks WebSphere Portal zone
- developerWorks AJAX resource center
- Meet the experts: Roland Barcia on AJAX and WebSphere
- Portlet Development Workbook
- Practical applications of AJAX in WebSphere Portal
- Using Ajax with WebSphere Portal
Get products and technologies
- Download a trial copy of IBM Rational Application Developer .