Tuesday, December 9, 2008

Advanced Lotus Connections customization - pt.1

In this blog-post-series I'd like to describe, how we achieved to integrate Lotus Connections into WebSphere Portal using the Web Application Integrator.
It will consist of three parts.

The first - this one - will provide a general overview of the solution and a little background information about the WAI and the Portal awareness.
The second one will the describe the modifications we had to apply on the WAI to achieve the double-top and sidebar-navigation.
The third part will describe how we integrated the WAI into Lotus Connections and how we made Lotus Connections Portal-aware.

After completion, all three parts will also be made available on Cattail or Quickr.

The intension was, to integrate Lotus Connections seamlessly into an existing Portal look&feel using the Web Application Integrator. The requirements were:
  • One Portal URL page for each Connections feature
  • All feature URL pages underneath a single Lotus Connections page
  • The Lotus Connections page underneath a Collaboration page
  • The Collaboration page as top-level page under Portal Home page
  • The double-top navigation and the sidebar navigation should always be visible
  • When accessing Lotus Connections outside of Portal, no Portal navigation should be shown but the default Lotus Connections top-bar navigation.
The starting point was, that the WebAppIntegrator officially only supports single-bar top navigation and that the Portal awareness is described as advanced topic in the WebAppIntegrator in General.
The customization consists of two steps
  1. Extending the WebAppIntegrator to support multiple navigation hierarchies
  2. Integrate the WebAppIntegrator into Lotus Connections and make the navigation Portal Aware
The article describes, how the solution was implemented, what has to be modified and which problems came up during the customization.

Web Application Integrator
The Web Application Integrator (WAI) is a solution for WebSphere Portal that allows the integration of external web applications into a Portal Look&Feel.
Basically, the WAI does not help to integrate applications physically into the Portal, instead it exports the Portal Look&Feel and Navigation to the web application and thus achieves a visual integration of the web application.

The Portal Look&Feel is injected into the web applications UI using javascript, which means the integration is done at runtime, on client side, during the render process in the browser.

In order to deliver the correct navigational state of the portal, the web application refers to a page in the Portal content model for which the navigation is rendered. In order to address this page, a URL is generated using the Web Application Integrator Portlet.

To have access to the theme content that should be displayed, the theme that should be used have to be enabled for the WAI. This is described in the WAI documentation. The standard IBM Portal theme is already enabled for being used with the WAI. However, this enablement only supports a single top-bar navigation.

How the Web Application Integrator works
A detailed description how the WAI works can be found in its documentation. But this section focuses on how it works inside the browser, especially how the HTML code looks like that is generated.

Regarding the visual display of the WAI, the WAI seems only to integrate at the WebUI’s top position as shown in the picture. With a little HTML background, such things are easy to implement by simply injecting the entire code surrounded by a div block as very first element inside the body element.
But the WAI works slightly different, since it wraps around the content respectively the application, providing closing html elements below the applications content area.

Taking this into account makes it easy to put the content into a table cell instead of a div block, which is a prerequisite for applying a sidebar navigation. The top navigation is placed inside a table row. This is depicted in the next image.

An alternative to this layout would also be to place the top navigation in a div block and the table with a single row and two cells containing the sidebar and the content area.
Deploying a different page structure is done in the webappintegrator/ files of the theme and consists basically of defining the opening tags.
How the navigation page structure is generated is described in the chapter Extending the WebAppIntegrator.

Portal Awareness
Portal aware means that the application is aware if it runs visually inside the Portal or outside of this. In other words, elements of the application are hidden or shown depending from the user has navigated to the application.

The basic principle how this is achieved is described in the Advanced Topics section of the WAI and is simply realized by appending a parameter to the URLs of the URL pages that are created in Portal. The customized application checks if the parameter is existent and shows or hides content accordingly. In order to keep this information while clicking through the application without modifying each link, a simple session cookie is set and the application just checks if the parameter exists in the request or as a cookie.

Unfortunately each module of Lotus Connection works differently and the sample code of the WAI documentation can’t be used. Furthermore, since each module is structured differently, a unique solution for almost every single module needs to be applied. How this is done is decribed in chapter Portal Awareness in Lotus Connections.


Anonymous said...

Thanks for covering this topic, can't wait for the next installments!

Luis Benitez said...

Where's the screenshot!!! ?? :)

Unknown said...

@Luis I left out the screenshot, since its a customer theme, I will post a neutral IBM one, when I have time... in the internal blog I posted it