IBM Rational Application Developer Version 7.5 Portal Toolkit: Part 4. Static page aggregation

With static page aggregation, you can create portal pages from static HTML layouts or templates in an IBM® WebSphere® Portal Version 6.1 project. This article guides you through the step-by-step process of creating, designing, customizing, and aggregating such static layouts by using IBM® Rational® Application Developer Version 7.5, targeting the portal server runtime environment. You do not need to know a lot about the underlying portal APIs to follow the steps in this article.


Jatin K. Varshney (, Associate Software Engineer, IBM

Jatin Varshney photoJatin Varshney is a software engineer for IBM India Software Labs in Delhi. He works on the Portal Designer and Web 2.0 features of the Portal Tools component of IBM Rational Application Developer.

02 July 2009

Also available in Chinese Vietnamese

System requirements

The author assumes that you have IBM® Rational® Application Developer Version 7.5 installed on your local system, as well as an IBM® WebSphere® Portal Version 6.1 server installed either on a local or remote system where you have administrative rights.

The advantages of using static pages

Until now, Web site designers used simple Web technologies such as HTML, cascading style sheets (CSS), and JavaScript to design the overall look and feel of a Web site, but portlets were usually created by Java™ or Java™Server Page (JSP™) developers. Now, you can use static page aggregation (SPA) to exploit the power of portlets by aggregating them with the static web pages. You can do this by using simple HTML markup in your static Web pages to create a complete portal site.

Figure 1. Aggregating a portlet in an HTML layout
Diagram of the process

The use of simple Web technologies, permits you to design the site layout by using your favorite Web authoring tools, such as Page Designer in Rational Application Developer or simple text editors. This gives you more control over the layout of the page than using the portal layout model.

You can include portlets as dynamic elements and containers as placeholders for portlets in your pages. You can display these portlets by using server-side aggregation, Ajax, or an IFrame element. You can also use portlet communication within a static page, for example, with wires.

Not only is static page aggregation simple and easy to use, it is also very powerful in exploiting the capabilities of portlets along with simpler Web technologies, such as CSS and JavaScript. This article first explains SPA concepts and then guides you through the following steps of using SPA with Rational Application Developer V7.5:

  1. First, you create a portal project and then portal pages with static layouts.
  2. Next, you create a portlet project that you add to your static page.
  3. Then, you create a portal page with a static layout (static page).
  4. Next, you edit this static page to add theme, portlet containers and portlet windows.
  5. Then, you publish your project to see the results of the first four simple operations listed above.
  6. Then you create themes for the static layouts and skins for the portlets in the static pages.
  7. Next, you can use the dynamic capabilities of portlets to automatically generate the navigation for your site.
  8. After that, you use internationalization to make your static page available in different locations worldwide.
  9. Then you use the same static layout resource archive file to create additional pages and to edit the static page that you created earlier.
  10. Finally, you publish your complete portal Web site that includes static pages.

Key terms

static layout
The layout of a page that is based on a plain HTML page and can contain references to portlets. In contrast, a dynamic portal page layout is defined structurally in a database on the server and managed by a page customizer.

static page
A portal page that references a static layout. A static page can be part of the portal page topology at any place (see the SPI content and navigation model). Apart from the rendering, it behaves like a default portal page, such as for access control.

dynamic layout
The standard portal layout, consisting of rows or columns; it persists in the database.

embedded static page
A static page that is rendered in the content area of the portal. The portal engine renders the banner, footer and navigation, but the content is exclusively rendered by the static layout.

stand-alone static page
A static page that renders the complete browser content. It is served by the portal servlet but has exclusive control over the complete page.

Create a portal project

You can create a portal project in Rational Application Developer by using the New Portal Project wizard, or you can import a project from WebSphere Portal Server Version 6.1 with the Import Project wizard and then customize it. One benefit of importing a project is that it lists all of the portlet definitions that are already deployed on the server so that they are available to be used in any portal page in the project. Of course, these definitions include the SPA navigation portlets, which are treated like utility portlets in static pages.

To create a new portal project:

  1. In Rational Application Developer Version 7.5, select File > New > Other.
  2. Select the Show all wizards check box.
  3. In the portal category, select Portal project, and then click Next.
  4. Click OK to enable the portal development capabilities and open the New Portal Project wizard (see Figure 2).
Figure 2. The New Portal Project wizard
The New Portal Project wizard
  1. Enter the project name, for example, FirstPortalProject.
  2. Select 6.1 as the Portal server version, and click Next.
  3. Select a theme, and click Next.
  4. Select a skin, and click Finish.

Figure 3 shows the new portal project open in the Portal Designer for editing.

Figure 3. The portal configuration open in Portal Designer
The portal configuration in the Portal Designer

The default configuration of the new portal project lists three portlets. You can use any of these portlets, as well as your newly created custom portlets in the same workspace in any page of the portal project.

  1. To see what portlets are available in your portal configuration, go to the Outline view and expand Elements > Portlets.

In Figure 4, you can see the three portlets:

  • Login
  • Edit My Profile
  • Search Sitemap
Figure 4. Portlets available in a new portal project
Portlets available in a new portal project

Import a portal project from the server

Rather than creating a new portal project from scratch, you can import the configuration and other theme and skin files from the server:

  1. In Rational Application Developer, select File > Import.
  2. Expand the portal category, select Portal, and click Next.
  3. Define a new WebSphere Portal Version 6.1 server.
    1. Specify either a local server as localhost or a remote server by providing its IP address.
    2. Make sure that the server is started and that you have administrative rights.
    3. Enter the credentials, and click Finish.
  4. Select the newly created server.
  5. Enter the name of the project, such as SecondPortalProject, and click Finish.

The portal project is created in the workspace with the name that you specified and contains all of the required files and portal configuration that you imported from the server. This project might have many more portlets than FirstPortalProject does, because the configuration contains all of the portlets that are deployed on the server. These portlets are available to use in your portal project.

Create a portlet project

The next step is to create a new custom portlet project (let’s say, for example, a standard JSR168 portlet with JavaServer Faces support). You will see how to consume this portlet in one of your static pages in the portal project.

To create a portlet project:

  1. Select File > New > Other.
  2. Select the Show all wizards check box.
  3. In the portal category, select Portlet project, and click Next to open the New Portlet Project wizard open (see Figure 5).
Figure 5. The New Portlet Project wizard
Portlet Project page
  1. Enter the project name, for example, MyWorkspacePortlet. Select WebSphere Portal v6.1 as the target runtime environment.
  2. For the Portlet API, select JSR168 Portlet, and for the Portlet type, select Faces portlet.
  3. Click Next twice, and then click Finish.
  4. When the portlet project is created, the MyWorkspacePortletView.jsp file is open for editing. Replace the "Place content here" text with This is my simple JSR168 Faces portlet.
  5. Save the file and close the editor.

Create a page

The portal page is one of the elements of the portal content model. A page in a portal project can be defined by using either dynamic or static layout. Pages that use dynamic layout are called normal portal pages, and pages that use static layout are called static pages. Static pages can be rendered either in the content area of the portal only (using the banner, navigation, and footer provided by the portal), or they can be fully rendered in the browser area.

On the basis of this rendering behavior, static pages are categorized as embedded static pages or stand-alone static pages. Start by creating an embedded static page, followed by a stand-alone static page.

Create a static page

If you want a portal page to use the layout of the static HTML file that you have already created or if want to create a fresh layout, you need to use the static page creation wizard in Rational Application Developer V7.5.

To create an embedded static page:

  1. In Portal Designer, select one of these options: Page, Label, or URL.
  2. Right-click and select Insert Static page and then select one of these options: Before, After, As child. Note: If you are using a URL node, it cannot have a child-level page.
  3. When the static page creation wizard opens (Figure 6), enter the title of the page as MyStaticPage.
Figure 6. The new static page wizard
Page title: Create portal page with static layout
  1. Leave the default values for Markup, File name, and Portlet window display option, and click Finish.

MyStaticPage is added to the portal configuration and the index.html static layout file opens for editing in the Page Designer.

The following points help to understand the parts of the wizard:

  • Markup check box: The supported markup in which the static layout can be provided to the portal page. The current SPA specification permits only HTML markup.
  • Title: The portal page title. If the page is an embedded static page, the title appears in the navigation bar.
  • File name: The name of the new static layout file that will open in the Page Designer for further editing and will function as the layout file of the MyStaticPage portal page. Important: This file must have an .html or .htm extension.
  • "Create using existing ZIP or HTML page" check box and fields: These are to specify the location of the archive that contains the HTML static layout file and related resources in the text box and to select the layout file inside of the archive in the drop-down box. Alternatively, you can use the "ZIP or HTML file location" field and associated menu to directly specify the location of the existing HTML or HTM static layout file rather than an archive. This would be copied into the workspace and used as the static layout of the portal page instead of the index.html that you specified earlier.
  • Portlet window display option: Specifies the metadata parameter for the page, which is used to render the portlets while displaying the page:
    • Included markup: The portlets are rendered inline at the same time as the static page.
    • Ajax: The content of the portlet is rendered asynchronously, and then the portlet fragments are embedded into the static page.
    • IFrame: The static page contains IFrames that render the portlets.

Now that you understand the parts of the wizard, we can explore the operation of the static page creation a little further.

After the static page is created, the index.html file opens in Page Designer for editing. This file resides in your portal project inside of the PortalConfiguration/Static Layout folder in your portal project, in a folder called page.uniquename, where uniquename is an internal name for the static page, such as page.ae354734c1.

You can create the directory structure for your static layout and other resources, such as images and styles, inside this folder but keep the location of the static layout file intact. If you change it, you have to re-specify the location of the static layout by using the Properties view of the static page.

The initial contents of the page look like the code in Listing 1.

Listing 1. Initial content of the static page
		<td> <div class="portlet-container" name="layoutcontainer1"></div> </td>
		<td> <div class="portlet-container" name="layoutcontainer2"></div> </td>

As you see, this file does not contain the <html> tag. This is what makes the page an embedded static page. If you write the contents of the static layout containing the <html> tag and its nested tags, such as <body>, just as with a normal HTML page, you get a standalone static page.

Now have a look at the changes in the portal configuration. The page named MyStaticPage is now visible in the navigation hierarchy, and you can see it in both the Portal Designer and the Outline view (Figure 7). You will learn how to configure it for portlets and containers a little later in this article.

Figure 7. A static page in the Outline view in the Portal Designer
MyStaticPage is the second item under Home

Edit the static layout

Now you need to edit the contents of the page. If you closed the HTML layout file for a static page, you can reopen it by right-clicking the page in Portal Designer and selecting Edit Layout (see Figure 8).

Figure 8. Opening the static layout of the static page
'Edit Layout' selected from menu

In the static layout file (such as index.html), remove all the contents and then save the file.

Create the content and markup

Now you can structure your site with the floating layout cascading style sheet (CSS).
Figure 10 shows a basic site structure with a header, side navigation, content area, and footer.

Figure 9. Basic layout of a static page
Illustration of page layout

To create a basic layout like this, add the content shown in Listing 2 to the index.html file.

Listing 2. Code for basic layout
<div id="wrapper">
	<div id="header">
		<h1>Static page aggregation</h1>
	<div id="left">The side navigation area</div>
	<div id="right">
           The content area <br> 
	<div id="footer">IBM</div>

To keep it simple, this HTML code uses just <div> tags. You can experiment with the tags or create a more complex layout to suit your need.

Add the style sheet for the theme

Now, to give the <div> tags the structure of the layout that Figure 10 shows, you can include the external CSS or create a CSS class definition in the <style> tag at the top of the index.html page, or you can even use the inline CSS. For this purpose, use the external CSS.

To add the style sheet:

  1. Create a "theme" folder inside of the PortalContent > StaticLayout> page.uniquename folder that contains the index.html static layout file.
  2. Then create a new CSS file inside of that theme folder.
  3. Select the project, and then select File > New > CSS.
  4. Browse the theme folder and enter the name of the CSS file as the theme.
  5. Click Next and Finish.

The CSS file is open for editing in the CSS editor. Now you can create the CSS styles in the source pane of the CSS editor.

  1. Right-click in the source pane, and click New.
  2. In the wizard, select the HTML tag and body (default choices), and click OK.
  3. In the New Style wizard, select the font. Browse to Verdana in the font list box, and click Add to add it to the list box.
  4. In the layout category, select margin and type 0. Then select padding and type 0, and click OK.

The style is inserted into the theme.css file as Listing 3 shows.

Listing 3. Changes to the theme.css file
	margin: 0px;
	padding: 0px;
	font-family: Verdana
  1. Similarly, you can add other styles for the div classes left, right, footer, and so on as Listing 4 shows.
Listing 4. Styles added to the div classes
	width: 100%;
	height: 100%

div#header {
	clear: both;
	height: 50px;
	background-color: #e3dffd;
	padding: 15px;
	text-align: center;

div#left {
	float: left;
	width: 20%;
	height: 100%;
	background-color: #e9fed3;	

div#right {
	float: right;
	width: 80%;
	height: 100%;
	background-color: #fffce1;

div#footer {
	clear: both;
	background-color: #ffebdf;
	text-align: center;
  1. Finally, add the link of the theme.css in the index.html file:
    <link rel="stylesheet" href="theme/theme.css" type="text/css">

The theme is now applied to the index.html page, and you can see it in the Page Designer.

Add the portlet container and portlet window

The static pages can contain the portlets and portlet containers just like normal portal pages. To use the portlets or containers in a static page include the class attribute values that are specified in the SPA specification with <div> tags . These class attribute values characterize the <div> tags with special meaning as either portlet containers or a particular portlet window.

Add a portlet container

You add a container in the static layout by using the <div> tag with the class attribute value of portlet-container. For example:

<div class="portlet-container" name="container_0"></div>

This <div> tag requires one more attribute: name. This is the name of a container and needs to be unique on the page. This attribute distinguishes different instances of the container on the same page (but you can use the same name in different pages in the portal).

To create a container in the static layout in the index.html page:

  1. Open the Palette view in Page Designer.
  2. Open the portal drawer.
  3. You will find two entries for the static page container and the static page portlet (see Figure 10):
    • Static Page Container
    • Static Page Portlet
Figure 10. The Palette view showing the items for a static page
Both entries are under 'Portal'
  1. Drag and drop the static page container onto the static layout file inside of the content area <div> tag, just after the <br> tag:
<div id="right">
	The content area <br> 
  1. In the static page container window (Figure 11), either leave or change the unique default container name, and click OK. (You can also open the dialog box by selecting Insert > Portal > Static page container).
Figure 11. "Insert static container" window
Instructions: Specify static container name
  1. Save the file.

The "container_0" tag is inserted in the static layout as you see here:

<div class="portlet-container" name="container_0"></div>

Now, look at the portal configuration in the Outline view in the Portal Designer. Figure 12 shows the configuration for the MyStaticPage file under Layout directory.

Figure 12. Outline view showing the portal page layout configuration
MyStaticPage highlighted in directory tree

The first column in MyStaticPage is the default root container. One of the children of the root container is the Row container. This row container is the static container that you added in the static layout by using the <div> tag. A row will be created inside of the root column container for every <div> tag that you put in your static layout file.

Do not nest <div> container tags as Listing 5 shows, because nested containers are not supported for static pages. If you try to do this, you get its effect in the top container only (container_0 in this example), and all the other containers will be ignored.

Listing 5. Do not nest <div> container tags
<div class="portlet-container" name="container_0">
	<div class="portlet-container" name="container_1"></div>

Another default child of the root container, which is also its first child and is a column container, is considered to be a hidden container. It persists in a static page configuration even if you do not define any container <div> tags in the static layout. This container holds all of the portlets that you add in the static layout that do not have any parent containers. Any orphaned portlets are adopted by this hidden container.

Add a portlet window

A portlet is added in the static layout by using the <div> tag with the class attribute value of portlet-window, as Listing 6 shows.

Listing 6. Code for adding a portlet to the static layout
<div class="portlet-window" name="portlet-window_0"
	style="portlet-definition: 'wps.p.Login'"></div>

This <div> tag for the portlet window still needs two more attributes to be complete:

  • name: The name of the portlet instance that is unique across the page (although not across different pages in the portal). It distinguishes different instances of the same type of portlet on the page.
  • style: The portlet definition or the type of portlet that you want to instantiate in your static page. The value of the style attribute contains the value of the portlet-definition attribute.

To insert a portlet <div> tag into the static layout page:

  1. Drag the static page portlet from the portal drawer of the Palette view into the static layout inside the container.
  2. In the Static page portlet window, select a portlet in the portlet table, such as MyWorkspacePortlet. (See Figure 13.)
Figure 13. Inserting a portlet within a static layout page
'Specify static portlet' view
  1. Edit or leave the default portlet window name, because it automatically takes care of its uniqueness across the page. Click OK to finish.

The portlet code is inserted in the static layout as you see in Listing 7.

Listing 7. Porlet code inserted into the static layout code
<div class="portlet-window" name="portlet-window_1" 
        style="portlet-definition: ''"></div>

The steps that you just followed completed these tasks for you:

  • Generated the unique name of the portlet in the context of the portal (you can edit this unique name in the Properties view by selecting the portlet in the Outline view of the Portal Designer under Elements > Portlets)

Note: If you change the unique name of the portlet in the Properties view, you must change all of its references in the static layout files to keep the portlet intact in the static page.

  • Generated the unique value for the name attribute of the portlet <div> tag
  • Added the <div> tag containing this portlet-definition to the static layout
  • Registered the entry related to this portlet in the portal configuration (if not already registered)
  • Added the MyWorkspacePortlet project as the referenced project in the portal project

While working with the portlet <div> tag directly in the static layout in the text editor, notice that the portlet must already be registered in the portal configuration. If it is not, the portlet is not inserted into the portal configuration, and saving the static layout returns an error message for the unavailability of the portlet, Therefore, the better choice is to use the portlet wizard, because it performs all of the related tasks for you.

Publish the portal project with the static page

Now that you have created a portal project consisting of a basic static page with a portlet in it, you can see how it works by publishing it to a local or remote instance of a WebSphere Portal Version 6.1 server. But before you can publish the portal project, you need to create a new server in the Server view.

  1. Right-click the portal project, and select Run As > Run on Server (see Figure 14).
Figure 14. Starting the Run on Server operation
Shows selections described
  1. In the Run on Server wizard, click Next.
  2. Select Remove all (if you have already performed the Run on Server operation in the same workspace).
  3. Click Next, and then click Finish.

When the project is published, the browser opens the portal project, and you can browse through your static pages (see Figure 15).

Figure 15. The embedded static page rendered in a browser after publication
View of the published page

Click to enlarge

If you created a static page as an embedded static page, you can easily browse through different portal pages while running your page on a server, because the navigation is already provided by the portal. But if you added the static page as a stand-alone static page in your portal project, you might need a way to navigate to other pages in the portal project.

The default WebSphere Portal Version 6.1 server provides you several utility portlets for the sole purpose of navigation. You can easily include these in the static layout by using their unique names. If you are working with a portal project that is imported from this server, you can insert these portlets into the static layout by using the same drag-and-drop operation that you performed for the other portlets.

You can use any of these navigation portlets:

Navigation portlet
<div class="portlet-window" name="portlet-window_0" 
        style="portlet-definition: 'wps.p.SpaNavigataion'"></div>

Use the Navigation portlet to add dynamic portal navigation to a static page. This portlet uses the portal navigation model to generate the navigation links for your static pages.

Breadcrumb Trail portlet
<div class="portlet-window" name="portlet-window_0" 
        style="portlet-definition: 'wps.p.SpaBreadCrumbTrail'"></div>

Use the Breadcrumb Trail portlet to add the navigation path to your static pages. The breadcrumb trail starts at the content root and goes down to the selected static page.

Page List portlet
<div class="portlet-window" name="portlet-window_0" 
        style="portlet-definition: 'wps.p.SpaResourceList'"></div>

Use the Page List portlet to add a dynamically computed list of links of portal resources to a static page. This list is produced dynamically with a POCURI (Piece of Content URI).

As already shown, <div> tags at specified locations in the static layout file might refer to portlets, containers, or navigation. When the page is rendered, the server replaces these <div> tags with the — possibly dynamic — content of the portlet and with a microformat that defines metadata for these portlets

For this purpose, the portal provides the following microformats:

  • portlet microformat: Defines portlet windows and portlet actions, such as Edit default settings, Configure, Maximize, Minimize, Personalize, and Delete.
  • container microformat: Defines portlet containers as placeholders for portlets.
    For drag-and-drop actions, the portlet microformat can provide the source to drag, and the container microformat provides the drop target.
  • navigation microformat: Defines the navigation if your static page is rendered as a stand-alone Web page.

The portlet window and portlet container microformats can contain object IDs, which the server can handle dynamically. When you create the static page, you can use CSS or JavaScript techniques that use the microformats to produce and render a user-friendly user interface.

Now look at these microformats in more detail to see how to implement them in your code.

Portlet microformat

Figure 16 shows the portlet markup that is returned by the server for a portlet <div> tag that is defined in a static page. To see this markup, use any markup inspection tool in your browser (such as Firebug in Mozila Firefox) when your static page with its portlet is rendered in the browser.

Figure 16. Markup (code) of a portlet in a static page
Screen capture of code shows collapsed references

A few of the HTML tags in this sample are intentionally shown collapsed, because they contain the object ID references that are handled by the server. You will find that the <div> tags, <ul> tags, and the <li> tags have certain class attribute values. These tags with the previously specified class attribute values define the complete structure of the portlet markup. See the following section for definitions of these class attributes:

Class attributes

portlet-windowThe same value that you provided when defining the portlet in the static layout. All of the values of other attributes of the <div> tag containing this class are the same as before, except the ID attribute that is added by server for the object ID of the window.

Denotes that a list of items follows.

Introduces the metadata section of the portlet. All metadata is encapsulated in this container so that it can be hidden by the CSS. The xoxo class further denotes that this contains a list of items.

Represents the localized title of the portlet. The language (lang=en) attribute identifies the locale.

Lists the portlet actions or operations that can be invoked in the portlet window. Note: Such operations are not necessarily actions in the sense of HTTP. Instead, some actions are safe interactions, whereas others can be unsafe, because they modify the server. In the list of actions, each interaction is either represented as a link to denote a safe interaction or as a form to denote an unsafe interaction (such as the Delete operation).

Describes the actual actions or operations. Those actions that would result in an actual operation are denoted by the selected attribute. In addition, each action is classified by an action-specific attribute to use CSS to style these actions (by adding action-specific icons, for example). The list of possible actions is computed on the server with the Operations Feed. This feed is extensible; therefore, new operations can be added over time.

Denotes the body of the portlet.

Identifies a selected item, either the portlet or an action. If it appears on the <div> tag for the portlet window, the portlet was the target of the interaction that produced the page.

(Optional) Denotes that the portlet window can be dragged around on the screen by users. This attribute is valid only if the portlet window is part of a modifiable portlet container, and if the user has the rights to modify the page and the container is not locked. See the container microformat to see how a drop target is represented and how the drag-and-drop operation can be performed. Note: A drag-and-drop action is triggered from the client side, but it is executed on the server.

Add the styles for the skin

If you see the static page that contains a portlet running on the server (Figure15), you will notice that portlets are shown without any formatting and the portlet actions are shown simply within a list just above the portlet body. Therefore, you might need to style them by using their microformat class attribute values, as described previously.

  1. Now add a CSS file in the skin folder under the page.uniquename folder of the static page.
  2. Name it skin.css.
  3. Add the following class values shown in Listing in the skin.css file by using the new style wizard or directly through the text editor.
Listing 8. Class values to add to the skin CSS
	margin-left: 0;
	padding-left: 0;
	list-style: none;

.xoxo ul{
	font-weight: bold;
	color: #FF9966;
	background-color: #F5F4EF;
	list-style-type: none;
	display: none;

	margin: 5;
	font-weight: bold;
	color: #85C329;
	background-color: #FAFBF7;
	border-top: 10px solid #CDCDCD;
	list-style-type: none;
	border-top-width: 5px;
	font-weight: bold;
	color: #FF9966;
	background-color: #F5F4EF;
	list-style-type: none;
	border-bottom: 3px solid #CDCDCD;
	cursor: pointer;
	padding-left: 10px;
.portlet-actions li{
	margin: 1;
	font-weight: bold;
	color: #FF9966;
	background-color: ##F5F4EF;
	list-style-type: none;
	text-align: left;

	border-bottom: 6px solid #CDCDCD;

Notice that the display property of the .xoxo ul class is none. This is for the first UL element inside of the <div> tag with the xoxo class, and it is nothing but the <ul> tag with the portlet-actions class attribute.With this value, the portlet actions are not displayed on the browser (in the collapsed state) until a user clicks the collapsed minus signs to expand them. You will provide a simple expand-collapse mechanism using JavaScript to render the portlet actions as a part of portlet skin.

  1. Now add the link of the skin.css in the static layout files:
	<link rel="stylesheet" href="skin/skin.css" type="text/css">

The next step is to add the JavaScript to make this skin collapsible.

Add JavaScript to make the skin collapsible

You can see that, in the initial state of the portlet, the portlet actions will not be shown, because you have used the style display property of none. To make the portlet skin actions collapsible, you need to add JavaScript. In this task, you create a new JavaScript file named skin.js in the skin folder of the page.uniquename of the static layout.

To create a new JavaScript file:

  1. Click File > New > Other.
  2. In the dialog box, expand the JavaScript section, and select the JavaScript Source file.
  3. Click Next.
  4. Enter the name as skin.js.
  5. Browse to the folder in which you need to create the JavaScipt file. Click Finish to open the skin.js file in the JavaScript editor.
  6. Rational Application Developer Version 7.5 provides support for JavaScript editing, using a Java-like editor.
  7. Add the following code shown in Listing X to the skin.js file.
Listing 9. Code to add to make the skin collapsible
 * Registers the onclick event of the document
document.onclick = function(e) {
	if (!e) e = window.event; // Now e is available to be used in all browsers
	var elem = getEventTarget(e);
	/* test if the element is a UL tag (case insensitive) */
	if (/UL/i.test(elem.tagName)) return;
	else elem = getAncestorElement(elem, 'tagName', /li/i);
	if (elem) {
		 * if xoxo is not prepended to className 'portlet-actions' i.e.
		 * portlet-actions is not a list, hence return
		if (!/\bportlet-actions\b/i.test(elem.className)) return;
		 * get the first UL child of the portlet-actions since it contains all
		 * the actions
		var ulStyle = elem.getElementsByTagName('ul')[0].style;
		/* toggle between the style of UL from block to normal */
		ulStyle.display = (!ulStyle.display) ? 'block' : '';

 * Returns the element node where the mouse was clicked
function getEventTarget(e) {
	var eventTarget;
	if (
		eventTarget =; // for W3C standards and Netscape
	else if (e.srcElement)
		eventTarget = e.srcElement; // IE
	/* If node type of eventTarget is not ELEMENT return its parent */
	return eventTarget.nodeType == 1 ? eventTarget : eventTarget.parentNode;

 * Returns the ancestor element of the node elem whose prop value is equal to
 * regexVal
function getAncestorElement(elem, prop, regexVal) {
	while (elem) {
		if (regexVal.test(elem[prop]))
			return elem;
		elem = elem.parentNode;
	return undefined;

The JavaScript code contains three functions:

  • The document.onclick function processes all of the on-click events in the document and is responsible for the collapsible action of the <ul class="xoxo portlet-actions"> tag, which defines all of the actions.
  • The getEventTarget function returns the element node in the document that was clicked. The document.onclick function needs this element node to be sure whether the user has really clicked on the <div> tag that contains Actions.".
  • The getAncestorElement function returns the <li> tag (as demanded by the document.onclick function), which is either the same as is or any ancestor of the clicked <div> tag.

The container microformat

Figure 17 shows the markup of the container that is returned by the server for a static page that defines the container <div> tag in its static layout.

Figure 17. Markup of a container in a static page
Screen capture of code segment

The container provides the following values for the class attributes:

A name for the container that is unique in the scope of the hosting page, which is the same value that you provided for the portlet container in the static layout. The ID attribute contains the object ID of the window.

A modifiable container that is the drop target of a drag-and-drop operation.

The form that represents the callback handler for drag-and-drop operations. The action contains a URL that uniquely identifies the drop target. You can add additional hints and drag sources dynamically to the form using JavaScript. For the drag source, use the attribute from the portlet microformat when defining the portlet.

The navigation microformat

Figure 18 shows the markup of the navigation portlet that is returned by the server for a static page that defines the navigation portlet <div> tag in its static layout. Because it is a portlet, the portlet microformat for the overall structure is still valid here.

Figure 18. Markup of a navigation portlet in a static page
Screen output of code

Notice that only the <div> tag with the portlet-window-body class defines extra markup with certain class attribute values to handle the different navigation states. These are the class attribute values:

The first child in a list, required for CSS styling.

The last child in a list, required for CSS styling.

An expanded node. A node can only be expanded if it has children and its navigational state is set to expanded.

A collapsed node. A node can only be collapsed if it has children and its navigational state is set to collapsed.

A lists of the actions that are available on the page, typically the actions used to expand or collapse the navigation nodes. For a page that is currently selected in the navigation, this list also contains the actions that are available for that page.

The page that is currently selected in the navigation.

Attribute that expands a collapsed node.

Attribute that collapses an expanded node.

Just as you can apply CSS and JavaScript techniques to the skin, you can also turn the container and navigation in your static page into a friendly user interface.


Add localized files

If you want your static page to support different languages or locales, you can do so easily courtesy of the static page aggregation technology. It supports localization without much effort. All you need to do is to give the different files names that follow the naming convention of the base file. These files can be HTML files, graphics files (JPG, GIF, and others), CSS files, JavaScript (.js) files, and so on.

Naming convention for localized files

If your base file name is base_file_name.extension , you need to name the localized version of the file base_file_name_locale.extension.

For example, for a base file named my_page.html, the English version of the file is my_page_en.html, and the U.S. English version of the file is my_page_en_us.html. These files need to be put in the same directory as the base file, my_page.html. Although these files have different file names, they logically represent the same resource and are referenced through their base names. The portal serves the localized version of the resource when appropriate.

Create a file to use in multiple pages

Now that you have created the static page with a static layout that references style sheets, JavaScript, images, and possibly other resources, you can create a .zip file with all of these resources and reuse the same work for the different static pages in the portal project.

To create a new static page by using the existing layout file:

  1. Select a node (page, label, or URL) in the Portal Designer.
  2. Select Insert static page > Before or After or As child (remember that URL cannot have a child-level attribute).
  3. When the new page with the static layout dialog box opens, as you have seen before, enter the static page title: MyStaticPage2.
  4. Select the "Create using existing ZIP or HTML page" check box to select the existing layout.
  5. Click Browse to locate the .zip file or the self-contained HTM or HTML layout file, and then click OK.
  6. If you chose the .zip file, select an HTM or HTML file from the "Select the Layout file" drop-down menu.
  7. Either ;eave the default values for all of the other options or change them according to your needs, and click Finish.
  8. The static page is created with the static layout file that you have in the .zip file, and this static layout file is now open for editing. Save the portal configuration.

This operation imports all of the contents of the .zip archive file into a folder under the page.uniquename folder. This is under the PortalConfiguration > StaticLayout folder in your portal project, where uniquename is your internal unique name of the static page that is used by the Portal Designer.

Edit the portal page properties with static layout

If you do not like the static layout that you have set for your static page, you can replace it with another layout file from your .zip file or even from a different .zip file. You can also change how the portlet window displays. Just select the static page in Portal Designer, and then perform the required steps on the Static Page tab in the Properties view (see Figure 19).

Figure 19. The Properties view of a static page in the Portal Designer
Screen segment

To update the static layout of the static page to a different layout file from the same .zip file:

  1. Select the Update Layout File drop-down menu, and select the layout file that you want to use
  2. The static page is updated to the static layout file that you just selected, and this layout file opens for editing. Save the portal configuration.

To update the static layout file of the static page to a layout file from a different .zip file or to a new static layout:

  1. Click open the "Replace static layout file" window (see Figure 20).
    1. To create a new layout file for MyStaticPage, click Finish.
    2. Select the Create using existing ZIP or HTML page check box to select an existing layout.
    3. Browse to the file location and click Finish.
Figure 20. "Replace static layout of the portal page" window
Screen capture showing selections described
  1. The static page is updated to use the selected static layout file, and this layout file opens for editing.
  2. Save the portal configuration.
  3. To change the portlet window display option for the static page, in the Properties view select the Portlet window display option and update it to the value that you want.
  4. Save the portal configuration again.

Publish the portal project with the static page

Now that you have created your portal project that consists of static pages, you can publish it to a local or remote WebSphere Portal V6.1 server.

If you do not require customized portal themes and skins (as in the case of stand-alone static pages), you can use the Deploy portal configuration only option to deploy the static pages completely. This approach is faster than deploying a complete portal project with themes and skins.

Other options

This article explained static page aggregation and guided you through the process of implementing it by using Rational Application Developer V7.5. There is much more that you can do with your static pages. You can include cooperative portlets in a static page and wire them by using the Portal Designer, create friendly URLs to your static pages to make them easy for user to find, and bookmark them.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, Agile transformation
ArticleTitle=IBM Rational Application Developer Version 7.5 Portal Toolkit: Part 4. Static page aggregation