Usage of Javascript/AJAX in Portal Theme Module

This section describes some of the functionality, libraries, and development processes with regards to implementing several usability enhancements using javascript in the Portal theme module.

Scope of Javascript/AJAX usage

1. Ability for drag and drop placement of portlet windows on a page

2. Ability for drag and drop placement to trigger an XMLHTTPRequest to the Portal server for persistence

3. Drag/drop usability should add a dropmarker on the destination slot, and shift other windows from that spot

4. Ability for user to remove a portlet window using a 'remove icon' on the portlet titlebar

5. Ability for portlet removal to trigger an XMLHTTPRequest to the Portal server for persistence

Libraries Selected

We chose to use the libraries from script.aculo.us, as they provided the functionality needed to achieve our needs. Note that these libraries are now bundled inside the jboss-portal.sar/portal-ajax.war/js/portal. We are currently bundling version 1.6.4 of this distribution, with some minor enhancements that are noted in the next section.

The main libraries used are:

1. dragdrop.js - Provides drag/drop functionality on sortable elements.

2. effects.js - Provides Effect functionality on div elements.

3. scriptaculous.js - Base scriptaculous libraries that extend prototype.js.

4. prototype.js - Base js library that makes it all possible. More information can be found here

Enhancements made to off-the-shelf libraries

There was one enhancement made to the off-the-shelf scriptaculous libraries, that allowed a dropmarker (dashed red line border) to appear when a window was hovering over a droppabble area.

Details on the patch can be found here and here

Custom library

JBoss Portal also introduces a custom javascript under jboss-portal.sar/portal-ajax.war/js/portal/event.js. This library was added by the portal team, and does the following:

• declares the Sortable elements (our portlet windows)

• declares what regions they are contained in (our layout regions)

• adds a WindowMoveObserver that triggers an AJAX Request when a portlet window is dropped on a region

• adds an AJAX function that has error handling sections and can send any number of calls based on an action to the server

• adds DOM update functions, to keep track of window positions and IDs, pre and post move

• adds an Effect function that calls the scriptaculous Effect.BlindUp(element) method, when a window is remove by the user

Note: event.js must reside at the foot of the page, or IE will throw an error, as all divs it is referencing must be declared first.