Chapter 25. Layouts and Themes

25.1. Overview

Portals usually render the markup fragments of several portlets, and aggregate these fragments into one page that ultimately gets sent back as response. Each portlet on that page will be decorated by the portal to limit the real estate the portlet has on the page, but also to allow the portal to inject extra functionality on a per portlet basis. Classic examples of this injection are the maximize, minimize and mode change links that will appear in the portlet window , together with the title.
Layouts and themes allow to manipulate the look and feel of the portal. Layouts are responsible to render markup that will wrap the markup fragments produced by the individual portlets. Themes, on the other hand, are responsible to style and enhance this markup.
In JBoss Portal, layouts are implemented as a JSP or a Servlet. Themes are implemented using CSS Style sheets, JavaScript™ and images. The binding element between layouts and themes are the class and id attributes of the rendered markup.
JBoss Portal has the concept of regions on a page. When a page is defined, and portlet windows are assigned to the page, the region, and order inside the region, has to be specified as well. For portal layouts this has significant meaning. It defines the top most markup container that can wrap portlet content (other then the static markup in the JSP itself). In other words: from a layout perspective all portlets of a page are assigned to one or more regions. Each region can contain one or more portlets. To render the page content to return from a portal request, the portal has to render the layout JSP, and for each region, all the portlets in the region.
Since the markup around each region, and around each portlet inside that region, is effectively the same for all the pages of a portal, it makes sense to encapsulate it in its own entity.
To implement this encapsulation there are several ways:
  • JSP pages that get included from the layout JSP for each region/portlet
  • a taglib that allows to place region, window, and decoration tags into the layout JSP
  • a taglib that uses a pluggable API to delegate the markup generation to a set of classes
In JBoss Portal you can currently see two out of these approaches, namely the first and the last. Examples for the first can be found in the portal-core.war, implemented by the nodesk and phalanx layouts. Examples for the third approach can be found in the same war, implemented by the industrial and Nphalanx layout. What encapsulates the markup generation for each region, window, and portlet decoration in this last approach is what's called the RenderSet.
The RenderSet consist of four interfaces that correspond with the four markup containers that wrap the markup fragments of one of more portlets:
  • Region
  • Window
  • Decoration
  • Portlet Content
While we want to leave it open to you to decide which way to implement your layouts and themes, we strongly believe that the last approach is superior, and allows for far more flexibility, and clearer separation of duties between portal developers and web designers.
The last topic to introduce in this overview is the one of portal themes. A theme is a collection of web design artifacts. It defines a set of CSS, JavaScript and image files that together decide about the look and feel of the portal page. The theme can take a wide spectrum of control over the look and feel. It can limit itself to decide fonts and colors, or it can take over a lot more and decide the placement (location) of portlets and much more.