Knowledge Base (Display) Knowledge Base (Display)

Ajax inter-portlet communication

AJAX Inter-portlet communication

This article describes how to send ajax requests from your own portlets to visioneo reportlet windows, it is mainly intended to developpers.

Overview

If you already tried the standard inter-portlet communication mechanism, you probably noticed your portal has to refresh the page when you send an event. It makes navigation less smooth as it could be with a full ajax communication, as described in this article. Check the 'storelet' live demo to see the difference between a standard portlet event and an ajax event. It is available in 2 versions:

Client-side ajax eventing

Currently the portlet specifications JSR 286 do not introduce a way to send client-side ajax events between portlets. Some portals have implemented a custom framework to manage this, but it requires to use specific java & javascript  portal API, and therefore cannot be used by a cross-portal reportlet.

The professional edition implements its own framework to allow ajax events on any portal. Using this feature will dramatically improve user's perception of your application!

How to send an ajax event

Sending an ajax event has never been easier: you just have to invoke a javascript function in your client-side portlet code (for instance in  'onClick' event of HTML buttons). No declaration, no include, no specific code or API, just invoke a function with your query string as parameter and the magic happens, whatever your portal is! For example:

visioneoManagerIPC.sendEvent("Year=2009&View=1");

This call would synchronize reportlet windows present on the same page, with 2009 year and "1" view (year-to-date in demo reports). You must obviously build this query string with report parameters and values expected by your Birt reports. Furthermore, as you can see in the demo, "Back to previous report" toolbar option works perfectly with ajax events, whereas it is reinitialized by standard portlet events.

That "visioneoManagerIPC" object is defined as soon as at least a reportlet window is present on your portal page.

Concrete example

On the live demo "inter-portlet communication page", here is how the html "ajax" button is defined:
 
 
<button
         id="apply-ajax"
    type="button" 
    onClick="VisioSendEventIPC();"
    title="Apply parameters, and synchronize the reportlets contents through an ajax event"> 
Ajax 
</button>  
 
 
And here is the function VisioSendEventIPC(), declared at the beginning of the jsp page. It has 3 steps:
  • Getting parameters values from your input fields (on this example we are using jQuery to achieve that). If these values may contain special characters, you may need to encode them with "encodeURIComponent" javascript function.
  • Building the query string: just concatenate parameters  with "&" as a separator
  • Sending this query string in an ajax event

If you already read the standard "inter-portlet communication" article, you may notice this html code below is very similar to the sample  "processAction" java code.

 
  <script type="text/javascript">  
    function VisioSendEventIPC(){
           var messageEvent;
           messageEvent="Year="+jQuery("#yearid").val();
           messageEvent+="&View="+jQuery("#viewid").val();
           messageEvent+="&Theme="+jQuery("#themeid").val();   
           visioneoManagerIPC.sendEvent(messageEvent);
     };                   
  </script>
 
 
That's all we have to do to send our selected values to the reportlet windows! Note we could invoke this function as well  from 'onchange' event of every parameter widget, so that we wouldn't need a refresh button anymore.

Encoding considerations

You should always use alphanumeric values for parameter names and values when it is possible. But sometimes we won't have any other choice but dealing with special characters. A boolean argument allows to specifiy if parameters are encoded or not in a IPC message. By default, the framework considers it is encoded from v1.1.01

visioneoManagerIPC.sendEvent("myparam=hello%23");

 

Your BIRT report actually receives  'hello#'

visioneoManagerIPC.sendEvent("myparam=hello%23",{encoded:false});
 

This time your BIRT report receives 'hello%23'

Community edition

From v0.9.4, this ajax event will be processed in the Community Edition too, with an exception indicating that your event has been correctly received. Thus when you develop your custom parameters portlet, you can test if in addition to work with community edition, it will take advantage of the professional edition as well.
 
 
For example, you should store in a preference a boolean indicating if your portlet must send standard or ajax events, and use this preference in a JSP page to run the appropriate action.
Tags: architecture developers
Average (0 Votes)
Most Recent