JBoss Portals and AJAX - Part 2

AJAX support for markup

Special tags are added to layout JSPs that facilitate the placement of AJAX features on a page. Similarly, renderers are used to interpret the tags and to render AJAX-driven content. The obvious advantage is the in-built support for the auto-creation and control of AJAX components on portal pages.

Layout markup

Layouts provide a structure for the creation and serving of portal pages. Layouts aggregate all of the content generated by the portlet, based on region and order, merge them with some additional content provided by the portal, and serve a response back to the user. By providing support for AJAX in the layout, helps facilitate the easy development and implementation of dynamic functionality in pages, with minimal effort.

Layout markup is implemented using JSP tags. The JBoss JSP tag library, portlet-layout.tld, offers tags that facilitate the implementation of AJAX features in layouts. A JSP layout can be changed to an AJAX-supported page simply by adding references to the tags. Hence, using tags also helps with the easy implementation of features.

The following is the layout page from the default portal generic layout ${JBOSS_PORTAL_HOME}serverdefaultdeployjboss-portal.sarportal-core.warlayoutsgenericindex.jsp, and shows AJAX support implemented as tags:

<%@ page import="org.jboss.portal.server.PortalConstants" %>
<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="http://www.w3.org/1999/xhtml">
<title><%= PortalConstants.VERSION.toString() %></title>
<meta http-equiv="Content-Type" content="text/html;"/>
<!-- to correct the unsightly Flash of Unstyled Content. -->
<script type="text/javascript"></script>
<!-- inject the theme, default to the Renaissance theme if
nothing is selected for the portal or the page -->
<p:theme themeName="renaissance"/>
<!-- insert header content that was possibly set by portlets
on the page -->
<%@include file="/layouts/common/modal_head.jsp"%>
<body id="body">
<p:region regionName='AJAXScripts' regionID='AJAXScripts'/>
<%@include file="/layouts/common/modal_body.jsp"%>
<div id="portal-container">
<div id="sizer">
<div id="expander">
<div id="logoName"></div>
<table border="0"
<td align="center" valign="top" id="header">
<!-- Utility controls -->
<p:region regionName='dashboardnav'
<!-- navigation tabs and such -->
<p:region regionName='navigation'
<div id="spacer"></div>
<div id="content-container">
<!-- insert the content of the 'left' region of the page,
and assign the css selector id 'regionA' -->
<p:region regionName='left' regionID='regionA'/>
<!-- insert the content of the 'center' region of the
page, and assign the css selector id 'regionB' -->
<p:region regionName='center' regionID='regionB'/>
<hr class="cleaner"/>
<div id="footer-container" class="portal-copyright">Powered by
<a class="portal-copyright" href="http://www.jboss.com/products/jbossportal">JBoss Portal</a><br/>
<p:region regionName='AJAXFooter' regionID='AJAXFooter'/>

Renderer markup

The portal combines the renderers and layouts to generate the final content. Enabling support for AJAX in the renderer just requires adding the statement <ajax-enabled>true</ajax-enabled> to the renderer descriptor.

The following example, at {JBOSS_PORTAL_HOME}serverdefaultdeployjbossportal.sarportal-core.warWEB-INFlayoutportal-renderSet.xml, shows the renderer configuration of the emptyRenderer RenderSet for AJAX support:

<renderSet name="emptyRenderer">
<set content-type="text/html">

AJAX support for content

Whereas the layout and renderer contribute to AJAX behavior at the markup level, JBoss portal's support for object-level configuration can be leveraged to provide AJAX support at the page level. The object property inherits a configured behavior from its parent. Currently, two features are offered for AJAX-driven content:

  1. Drag and drop: Facilitates easy movement of portlets to various locations on screen using the mouse.
  2. Screen Refresh: Allows sub-components of pages or individual portlets to refresh themselves without refreshing the entire page.


As the name suggests, this feature is triggered by a user action, and allows a portlet to detach itself from a specific location on the page and move to a different location on the page. This allows for the customization of the user interface to a form that is most convenient to the user. The dynamic view behavior comes from a combination of DHTML and asynchronous server-side communication.

Due to the nature of the behavior, drag-and-drop capability is available and effective only in dashboard pages where there are multiple portlets and the page layout can be personalized. The feature is allowed by default on the dashboard, but can be turned off by setting the value in the configuration file to false.

The following is a snippet of the default object configuration file ( jboss-portal.sar/conf/data/default-object.xml ), which illustrates the enabling of the feature. Please note that this can also be configured using the administration console user interface of the JBoss server.

<!-- Set the dnd property -->

<name>theme.dyna.dnd_enabled</name> value enables or disables the drag-and-drop behavior.

Partial content refresh

One of the most expensive processes in a portal is the refresh of portlets when the page is generated. For every user action on a page, the portal calls all of the portlet methods in a serial, but non-specific order, which involves a significant amount of time and server-side processing. Partial content refresh support mitigates these issues to a large extent with an effective use of client-server asynchronous communication. When the state of a single portlet changes, a partial content refresh facilitates the update and refresh of only that portlet, instead of for all of the portlets on the page. This prevents the regeneration of the whole page and the initialization of all of the portlets on the page.

The following image illustrates the partial content refresh flow:

JBoss Portals and AJAX - Part 2


The partial refresh capability is compatible with the JSR-168 portlet API, which allows for programmatic update of portlet states during runtime.

Partial refreshes can be enabled through portal object configuration or through configuration at the default server level.


Portal object configuration

To implement partial page refreshes successfully, the properties of the portal objects need to be updated to include the property, theme.dyna.partial_refresh_enabled, which takes the values true or false. The deployment descriptor appears as follows:

<!-- Set the dnd property -->
<name>theme.dyna. partial_refresh_enabled</name>

For changing the behavior during runtime, the property editor of the management portal can be used to set the values at the default server level. Once set, all of the pages in the portal automatically inherit the property. The default portal configuration is shown in the following screenshot:

JBoss Portals and AJAX - Part 2


Portlet configuration

Although the default portal configuration enables partial refreshing for all portlets, it is also important to understand when a portlet would actually use a partial refresh. Having this knowledge helps us to control the behavior at the portlet level.

The server, by default, enables partial refresh for action and render links. However, there are the following exceptions for which the whole page is refreshed:

  • Forms with GET requests. Using a GET request is discouraged by the portal specification. Hence, this should not be of significant concern
  • Form uploads
  • A window in a MAXIMIZED state. Partial page refreshes will not function when the window is entering or exiting a MAXIMIZED windows state.

There are, however, a few scenarios where we don't want to use a partial refresh at all. In such cases, partial refreshes can be disabled by using the following configuration in the portlet descriptor file, jboss-portlet.xml.


Setting the <partial-refresh> value to false prevents partial refreshes of portlets when they are invoked.

Constraints in implementing partial refresh

Although partial refresh is a powerful option, it has certain constraints on both the client and server sides.

Inconsistent session attributes

When a page is partially refreshed, the state of the page and its relationship to the portlets on the page become inconsistent. The direct impact of this is the session variables. If a partially-refreshed variable updates a session variable, a different portlet using this same variable will continue to use old data and might not be able to update to the latest session data.

In such cases, selective enabling of partial refreshes for portlets should address the problem.

Non-AJAX interaction

The AJAX implementation for partial refreshes is triggered by DOM events generated by the user in the browser. However, the user doesn't trigger these events. The portal JavaScript has no way of knowing the request, and hence might refresh the whole page.

A good example of this is the direct programmatic submission of forms, instead of relying on browser events for submission.

For issues like these, care should be taken when coding the portlets, and using constructs that do not generate DOM events should be avoided.

Considerations for AJAX implementations

Although AJAX is an exciting technology and provides significant advantages in terms of performance, usability, and implementation, there are certain scenarios where using AJAX is not a good fit. This is especially true when a lot of custom development is involved in using AJAX libraries.

Some of these are discussed in the following sections.

Global variables

One of the important aspects of portal-specific development is the obvious collision of variables declared at the global page level. Due to the nature of portals, a page typically consists of multiple portlets with their own local variables. Creating global variables almost invariably exposes the application to confl icts with local variables.

One solution might be to assign name spaces along with the variable declaration.

State management

With constant partial page refreshes happening, and content being refreshed through AJAX implementation, it is very difficult to keep the state of the page consistent. Page refreshes and content refreshes can occur at any given time, triggered by any portlet on a page. Hence, building a portlet with dependencies on a page can cause serious problems. Similar issues can crop up if a user uses the Back button on the browser.

All calls need to be atomic and should use techniques such as cookies to store states.

Visual cues

Users of web applications prefer to continuously receive the status on their actions, without which they tend to get impatient or nervous. Most AJAX functions and calls execute in the background with no obvious sign in the browser that the user needs to wait and that the browser is busy. Portals with multiple components on pages sometimes operate independently, further exacerbating the issue.

Hence, AJAX implementation should always use techniques that provide continuous visual cues to the user.


AJAX is a powerful tool. Used appropriately, it can provide tremendous value in terms of features, usability, performance, and implementation. The implementation is relatively native and simple with no need for special skills or plug-ins, other than the ones that web developers normally have. With the adoption of the Portlet 2.0 specification, AJAX development has become significantly easier and more reliable. Our example in this article showed how easy it is to develop and deploy AJAX-based portlets.

JBoss portal supplements custom development of portlets enriched with AJAX, with its own set of pre-packaged baked-in support for features such as AJAX-enabled layouts, drag-and-drops, partial refreshes, and so on. Portlets can be configured individually to provide or block AJAX features. Although it is powerful, it also comes with certain limitations. Developers can build a more robust portal solution using AJAX if they bear in mind these limitations.

You've been reading and excerpt of:

JBoss Portal Server Development

Explore Title
comments powered by Disqus