Resources

Overview

TIBCO PageBus(TM) is an in-browser event bus implemented in JavaScript. It enables widgets in a Web page, such as rich portlets, to in interact with each other in a loosely-coupled manner by publishing and subscribing to application-specific events. When your rich portlets interact with each other via application-specific events such as "customer.select" and "order.cancel", it becomes easy to create, extend, modify, combine and maintain portlet-based rich internet applications.

This document explains how to make rich portlets in the same portal page communicate in "real time" via TIBCO PageBus.

The elements of the solution are as follows:

1. Deploy pagebus.js in your Shared Template Application (or somewhere else that browsers can access)

2. Include pagebus.js in your portal pages

3. Define the application-specific events you want to use in your application.

4. Add PageBus publishers and subscribers to your rich portlets.

Deploy pagebus.js in your Shared Template Applicaton

Browsers will need to access pagebus.js.

A good place to put pagebus.js is in the following location, within your PortalBuilder Shared Template Application WAR:

/sta-pb/PortalTemplates/UtilityScriptlets/pagebus/pagebus.js

However, you could put pagebus.js somewhere else instead. If you do so, be sure to change the path in your layout templates to point to this location.

Include pagebus.js in your portal pages

If many of your portal pages may contain portlets that rely on PageBus, then you should probably include the following in your page layout templates:

<script type="text/javascript" src="/sta-pb/PortalTemplates/UtilityScriptlets/pagebus/pagebus.js"></script>

If you only intend to leverage pagebus.js in a few portlets on a few pages, you might want to use the technique discussed in Portlet Items with Dependencies instead.

Define application-specific events

Your application will make use of customized, application-specific events with names like "org.example.city.select" and "org.example.customer.delete".

To define an event:

1. Decide on a subject name, e.g. "org.example.portfolio.select". I strongly recommend using your organization's reverse DNS name as a prefix (e.g. com.example) so that when different organizations define events and solutions are integrated with each other, collisions do not occur.

2. Specify the payload. This should be a JavaScript object that contains data but no functions, e.g.

var myDataObject = { city: "Boston", region: "MA", country: "US" };
var anotherDataObject = {
  portfolio: "USTelcos", 
  members: {
    [ sym: "T", exchg: "NYSE" ],
    [ sym: "VZ", exchg: "NYSE" ],
    [ sym: "S", exchg: "NYSE" ],
    [ sym: "CTL", exchg: "NYSE" ]
  }
}

These events will serve as interfaces between your portlets. A well-designed set of events will allow you to create UIs that can be evolved and expanded over time. Best practices for defining event messages and subjects are described in the PageBus Developer's Guide, available at pagebus.org.

Make your rich portlets use PageBus

It is very easy to make a rich portlet publish on a PageBus subject. Simply add the following script to some event handler in your rich portlet:

PageBus.publish("my.subject.name", yourDataObject);

For example, create a portlet item (perhaps an HTML Editor portlet) that contains the following markup:

<a href="#" onClick="doMyPublish();return false;">Click me to publish!</a>
<script type="text/javascript">
doMyPublish = function() 
{
  var myEventDataObject = { text: "hello world!" };
  PageBus.publish("my.subject.name", myEventDataObject);
}
</script>

It is also very easy to make a rich portlet subscribe to a PageBus subject. For example, create a portlet item (perhaps an HTML Editor portlet) that contains the following markup:

<script type="text/javascript">
myOnDataFunction = function(subject, eventDataObject, subscriberData) 
{
  alert(eventDataObject.text); // Do something interesting with the event payload
}
PageBus.subscribe("my.subject.name", null, myOnDataFunction, mySubscriberData);
</script>

PageBus calls myOnDataFunction every time any portlet publishes an event data object on the subject "my.subject.name".

A single portlet item can publish and subscribe on many different subjects.

For more information about the publish and subscribe functions, including the parameters of the subscribe function, see the PageBus Developer's Guide.

Using other features of TIBCO PageBus

TIBCO PageBus has other features that rich portlets can use to coordinate their interactions, such as a store/query mechanism. See the PageBus examples at pagebus.org and/or the PageBus Developer's Guide for more information.

Products that embed TIBCO PageBus

A number of products from TIBCO and third parties embed TIBCO PageBus. The TIBCO products include:

- iProcess Web Client Components: The iProcess Web Client Components use TIBCO PageBus to communicate with each other and with other widgets.

- iProcess Workspace: Same as WCC

- Ajax Message Service: integrates the PageBus running in the browser with a Java Message Service implementation on the server side.

More Information

TIBCO PageBus can be obtained at www.pagebus.org.

For more information, including example code and TIBCO General Interface examples, consult:

- www.pagebus.org

- The TIBCO PageBus Developer's Guide, which can be found at that location.