of contents | Next | Previous
Analysis of J2EE Quickr theme layout architecture
The following article explains the purpose of a Quickr Theme and provides an
analysis of the components which make up the Quickr theme layout.
What is a Theme
A Quickr theme controls the look and the layout of a TeamPlace: its fonts
and background colors; how an element looks when it is selected; where the
navigational controls appear; and so on. When you create a TeamPlace, you can
select a theme by choosing from a gallery of predefined themes. You
can also modify an existing theme or create a new theme. Using a custom theme,
you can give your TeamPlace a strong brand identity, or design it to look like
other corporate sites. Finally, by customizing the theme, you can supply
additional functionality as well as provide a unique look for your
The J2EE Quickr theme layout architecture
This section provides an overview of the Lotus Quickr theme and its
artifacts. By convention, WebSphere Portal themes are broken down into four
contains a set of theme files as suggested by the folder name. Essentially, a
theme includes four main elements: Java Server Pages, stylesheets, script
files, and theme graphics that include image and icon files.
The main theme fragments are:
- Theme Banner
- Page header
- Top Navigation row
- Page area (Portlet render area)
- Page footer
Figure 1: Theme Layout
So, the overall structure can be defined as:
Figure 2: Theme Layout
Layout Components : Theme JSP
Java Server Pages are text documents that contain static data and dynamic
data. Static data can be expressed in any text format where dynamic data is
used to construct the dynamic content of the page. Lotus Quickr JSP files are
located at the root of the QPG folder located in the WebSphere Portal themes
The theme is composed of a set of files that consist of a parent JSP file
and subsequent fragments of the parent JSP. The fragment JSPs are included from
within the parent JSP, and by convention, they are saved with JSPF extensions.
For most requests, the portal page is rendered starting with Default.jsp in the
themes directory unless the request has been modified by a
newWindow="true" parameter. In this case, the page is rendered using
Plain.jsp. Following figure shows an overview of all the theme files and how
they are laid out with respect to the parent file and to each other.
Figure 3: Theme file hierarchy
Default.jsp is the parent JSP file that includes the JSP
fragments (denoted by the JSPF extension) and tag libraries that are needed to
render the theme elements. The fragments are compiled into the servlet for
Default.jsp. Whenever you make a change to a fragment, resave Default.jsp to
force the servlet to recompile. Resaving Default.jsp ensures that the servlet
picks up the latest modifications to the fragments.
The head.jspf file is the first fragment included in
Default.jsp. This file contains header elements of an HTML page. In the Lotus
Quickr theme, all the stylesheets and client-side script files are linked from
head.jspf. The page title and text direction are also set in this file. For
better performance, link any additional files added to the theme in head.jspf.
This approach consolidates all downloads to the beginning of the page and
avoids retrieval in the middle of page rendering.
The banner.jspf file, as suggested by its name, displays
the page banner shown in figure below. The banner includes the product logo,
search box, and action links to login and logout. It also includes the banner
breadcrumb that displays the Back To Home button, a button that lets you expand
or compact the screen width, and Lotus Quickr help. Like Default.jsp, the
banner also includes fragment files that are compiled in banner.jspf.
These fragments are:
- banner_toolbar.jspf. This fragment renders the toolbar
at the top that includes the product logo and search control box and links to
login and logout.
- banner_searchControl . This is a subfragment of
banner_toolbar.jspf. It renders the search control box at the right end of the
- banner_crumbtrails.jspf. This fragment renders the Back
to Home link on a theme page.
- banner_globalActions.jspf. This fragment contains the
code that points to the links to expand and compact the page width and to Lotus
Figure 4: Page banner
This section of the theme, contained in pageHeader.jspf and shown in
figure 5 below, displays the application header. In this JSP,
you can find the source that retrieves the application name and favorite
status. The Customize link that is displayed at the right end of the
application header is also rendered in this fragment. The Customize link
displays a dynamic palette that is rendered with pageHeaderContent.jspf and
shown in figure 6.
Figure 5: Page Header
Figure 6: Customize palette
The pageHeaderContent.jspf file contains the source that
renders the customize shelf. The customize shelf provides the ability to add
components, members, and new pages or to modify the properties for an existing
The topNav.jspf file is a simple and short file that
renders the tabbed navigation row that allows users to switch between different
components in the same application; see figure 8. The fragment uses different
styles to differentiate between the selected and unselected
Figure 7: Tabbed navigation
The sideNav.jspf file renders subpages created under the
top-level navigation node in a place. By default, child nodes to the parent
page in a place are displayed in side-tree navigation. In a later section of
this article, we discuss an example to change the default styles to a
horizontal navigation style instead.
The footerLarge.jspf file renders the section at the bottom
of the page that contains quick links to commonly accessed areas of Lotus
Quickr; see figure 8 below. The links are internal links to
portal pages, and they appear in an expanded or a collapsed state.
Figure 8: Footer
Images are used for icons and tools in the theme pages. These files are
placed in the images folder at the root of the theme directory at:
When you customize a new theme, you can modify the existing image file or
create new ones and place them in the images directory.
Image files are spread across various subfolders that are created to keep
the image files grouped with respect to various sections of the page.
The layout content is contained in the theme JSP files, but the presentation
details of the content are defined in stylesheets. Lotus Quickr stylesheets are
located in the same folder with the theme JSP files at:
Similar to the theme JSPs, the stylesheets are broken into several fragments
that are included from the parent stylesheet named styles.jsp. Stylesheets are
saved as JSP files to accommodate differences in locale and browser support.
Similar to default.jsp, the parent stylesheet must be recompiled to pick up the
updates to the fragments included in it. Here is a list of stylesheets and a
brief description of the contents of each file:
- styles_cacheSettings.jspf. Used to set the cache headers
for all CSS JSPs.
- styles_extension.jspf. Contains theme extension styles.
- styles_help.jspf. Contains the styles used to render
Lotus Quickr help content.
- styles_ibm.jspf. Contains styles for the WebSphere
Portal administrator portlet page.
- styles_ibmportlet.jspf. Exclusive to the Lotus Quickr
theme, contains styles used by the document library and web content management
components in Lotus Quickr.
- styles_oobQuickr.jspf. Contains styles for the My Places
- styles_people.jspf. Contains styles in the person card.
- styles_portlet.jspf. Contains the default styles that
are shipped with the IBM theme.
- styles_qpg.jspf. Contains styles for Lotus Quickr
administrative portlets only.
- styles_rules.jspf. Sets browser- and locale-specific CSS
- styles_theme.jspf. Contains general theme styles that
are used in the theme files and fragments.
- styles_themeSolo.jspf. Is included when the toolbar
render is turned off. Adjusts the page elements to display well without the
A color palette allows you to set the color scheme of the theme. In
WebSphere Portal, the color palette is defined by a property file that contains
key value pairs holding references to colors and graphics used in the theme.
This is a useful concept that lets users change the color scheme of the theme
without making any changes to the stylesheets. You can assign a color palette
to an entire theme or to a single page depending upon the design requirements.
Refer to the section, "Using color palettes in the theme," in the
WebSphere Portal Infomation Center (See URL below) to get details on creating,
using, and referencing color themes in WebSphere Portal.
Out of the box, the QPG theme uses the default color palette. You will reuse
it in this customization.
A theme policy is an XML file that controls how various parts of the theme
are rendered on a page. This design concept allows you to display a single
theme in multiple ways.
Figure 9 : Theme Policies
Theme policies are an important part of the theme and theme customizations.
Lotus Quickr installation is shipped with two policies used to render the Lotus
Quickr pages: QuickrMyPlaces and QuickrSpaces.
To set up a new policy, you must create and install it using the XML
configuration utility as described in the WebSphere Portal Information Center .
(See the URL provided below.)
The Quickr skin
Skins represent the wrapper that goes around the components. They are made
of row containers, column containers, and controls. The containers act as a
wrapper for the inside portlet application, and the control section renders
By default, Lotus Quickr uses QuickrSkin, which was designed specifically to
work with Lotus Quickr themes and pages. In the "Getting Started"
section of this article, we created a custom_skin from the default Lotus Quickr
skin. This skin directory contains three main JSP files:
- UnlayeredContainer-H . This is the row container.
- UnlayeredContainer-V . This is the column container.
- Control.jsp . This renders the controls for the portlet
Abstract - This article explains the purpose of a Quickr Theme and provides an analysis of the components which make up the Quickr theme layout.