Designing portal site structure and page layout using IBM Rational Application Developer V7 Part of a series on portal and portlet development

(1)

Designing portal site structure and page layout

using IBM Rational Application Developer V7

Part of a series on portal and portlet development

By

Kenji Uchida

Software Engineer

IBM Corporation

Level: Intermediate

August 2007

(2)

Abstract

IBM® WebSphere® Portal Version 6 introduced new features, such as Color Palette and Theme Policy, which make developing a portal site faster and easier. However, that task is still complicated for developers who are not knowledgeable about portal structure. In addition, portal themes are too complicated for Web designers who need to design the look and feel of the site, because themes consist of hundreds of JSP, CSS, properties, and image files. Now, IBM® Rational® Application Developer Version 7 makes it easy for portal site developers to create page and portlet layout structures and for Web designers to design the look and feel of the portal site. This article describes these Rational Application Developer V7 and WebSphere Portal V6 features.

Introduction

Rational Application Developer Version 7 is a premium product that is part of the IBM® Software Delivery Platform (SDP). Its many benefits cut across various dimensions that affect developers. It is a true integrated development environment (IDE), because it provides a single environment for designing, building, testing, and deploying, all from the same workbench. The portal tooling components make portal site development and portlet application development faster and easier. You can start by creating either a portal or portlet project.

This article shows you the main features that help in designing a portal site that targets IBM WebSphere Portal Version 6. Basically, designing the look and feel of a portal site is separated into two different tasks:

• Configure page structure and settings stored within a database on the server. • Generate and edit Web artifacts, such as JSP, CSS, and image files.

Rational Application Developer V7 enables you to edit the structure, settings, and artifacts. The portal project stores the portal configuration in an XML file in the

PortalConfiguration folder and stores the Web artifacts in the PortalContent folder.

The XML file can be edited visually by using the Portal Configuration Editor, and Web artifacts can be edited visually by using the Theme Editor. You will experience both of them in this article.

Create a portal project

When you use Rational Application Developer to work on your site, the first thing that you need to do is to import the portal configuration and resources from your portal server. Rational portal tooling provides the Import Portal wizard, which creates a portal project in your workspace and copies your portal configuration and resources from that server into your current project.

Although starting from the import is preferable, you can also create a portal project by using the New Portal Project wizard. The new portal project is almost the same as

(4)

imported one, but the newly created one has fewer content nodes than the imported one. Table 1 shows the portal project structure.

Table 1. Portal project structure and resources

Node Description

Deployment Descriptor Shortcut to the PortalContent/WEB-INF/web.xml file. Usually, you don’t have to modify it.

Java resources folder Java resource files. The nls folder contains translated properties files used in themes. On the server side, they are packaged in the

<Portal Home>/shared/app/wp.ui.jar file or located in the <Portal Home>/shared/app/nls folder as separate files. When the portal

project is built, these files are copied into the <Portal

Project>/PortalContent/WEB-INF/classes/nls folder.

PortalConfiguration folder

Folder containing ibm-portal-topology.xml file, which is a portal configuration model.

Portal Configuration editor

Shortcut to the <Portal Project>/PortalConfiguration/ibm-portal-topology.xml file. By double-clicking this icon, you can open the Portal Configuration editor. This shortcut has portlet icons, which represent portlets installed in your portal site. By drag and dropping a portlet icon to the Portal Configuration editor, you can insert the portlet into a portal page.

PortalContent folder Folder with Web resources. The folder contains themes, skins and screens folders and resources. On the server side, these files are located in the <WAS

Profile>/installedApps/<node>/wps.ear/wps.war folder.

Skins Shortcuts to skins installed into your portal site. By double-clicking one of the skin icons, you can open the Control.jsp file associated with the skin. By dragging the skin onto a portlet in the Portal Configuration editor, you can change skins applied to a portlet. Themes Shortcuts to themes installed into your portal site. By

double-clicking one of the theme icons, you can open the Default.jsp file associated with the theme. By dragging the theme onto a page or a label node in the Portal Configuration editor, you can change themes applied to a page or a label.

Define page structure

To better understand this section, it is helpful to understand portal models.

Portal models

Content nodes: These can be pages, labels, or URLs. In the Outline view, pages are

shown under Layouts, and labels and URLs are shown under Elements > Labels and Elements > URLs, respectively.

(5)

• Pages display content as portlets, and pages can contain other pages, labels, and URLs.

• Labels do not display any content but can contain pages, labels and URLs. • URLs are links to external Web sites or internal pages.

Navigation model: The Navigation model describes the topology of navigation in the

form of a tree structure (directory) of content nodes. It is referred from top or side

navigations to show appropriate sets of content nodes. In the Outline view, you can see the tree structure under the Content Root node, which is the root node of this model.

Layout model: The Layout model describes the layout of portlet within a page. It

consists of rows, columns, and portlets. Portlets are arranged at the center of a portal site, based on this model. In the Outline view, you can see the Layout node, which is the root node of this model.

Defining page layout

When a portal project is created, the initial Navigation model includes Page 1, which has a row and a column. Rows and columns can contain other containers or portlets. Rows arrange contents horizontally and columns arrange it vertically. You can add containers by dragging them from the Palette view.

Figure 1. Inserting a column

Drag and drop

Tip: The same type of container as the parent cannot be inserted. This means that

columns or portlets can be inserted into a row, and rows and portlets can be inserted into a column.

Inserting content nodes

You can insert content nodes into your portal site by using the drag-and-drop method. Drag the page, label, or URL from the Palette view over the position where you want to insert it. You can see vertical or horizontal bar to guide the insertion position. When you

(6)

drop the node where you want it to be, you’ll see the Insert dialog. For a page, you can specify the title and initial layout. For a label, you can specify the title.

Figure 2. Inserting a page

After the content node is inserted, you can modify its properties in the Properties view. When the Properties view doesn’t show the properties of the node that you are

interested in, you can click the appropriate node in the Portal Configuration editor or in the Outline view. Figure 3 shows the Title page for Label. The default title, Label1, has been changed to Order Tracking.

Figure 3. Title page of the Properties view

Drag and drop

Inserting portlets

You can add portlets into a page by using the Insert Portlet Dialog. If you imported a portal configuration from the server, a list of available portlets on the server has been transferred into your portal model. If you have a portlet project in your workspace, you can add your portlets into a portal page. In this case, you can use the Insert Portlet

(7)

dialog, but you can also drag it from the Portlet Deployment Descriptor in the Project

Explorer. Figure 4 shows that the OrdersPortlet portlet is inserted into the Order Info

page. The Cooperative portlet project can be imported from the Sample Gallery. Figure 4. Inserting a portlet

Drag and drop

Tip: The portlet doesn’t necessarily exist on the server or your workspace. You

can also insert portlets provided through Web Services for Remote Portlets

standard, which you can specify in the Insert Portlet dialog. After you retrieve a list of portlets provided by the producer, the portlets are listed in the Insert Portlet dialog. The list of portlets can be updated in the Properties view.

Adding a page to Quick Links

Quick Links is a feature introduced in WebSphere Portal V6. At the bottom of the portal site, you can see the Quick Links toolbar, which enables you to quickly access major areas of your site.

Figure 5. Quick Links toolbar

Rational Application Developer V7 enables you to add your own links to Quick Links toolbar. Quick Links are normal internal URLs that are located under specific nodes. To add an icon to the Quick Links toolbar, follow these steps:

1. In the Outline view, expand Content Root and select the Quick Links node. 2. Drag the URL from the Palette view onto top navigation in the Portal

Configuration editor.

3. In the Insert URL dialog, select Internal for the Type, select a page to create a link, and then change the title for the link.

(8)

of your portal page

el of a portal site. It consists of several resources, such ), CSS, image, and properties files. In most cases,

ed

The IBM theme consists of components. Basically, each component is described by a SP fragment file, which is included directly or indirectly from the Default.jsp file, and After you insert the internal URL under the Quick Links label, the icon shows up on Quick Links toolbar automatically.

Customize the look and feel

Theme JSP structure

A theme defines look and fe asJava™Server Pages (JSP

rendering a portal page starts with the Default.jsp file, which is in the

themes/html/<Theme Name> folder. WebSphere Portal V6 includes a theme nam

IBM. Figure 6 shows the composition of the IBM theme.

Figure 6. Theme structure

Banner

Top navigation

Side navigation

J

some of them include other JSP fragment files. Figure 7 shows the hierarchy of JSP and JSP fragment files used in the theme.

Footer

(9)

Figure 7. Hierarchy of the IBM theme JSP files

Footer Screen Side Navigation Top Navigation banner.jspf Banner_crumbtrail.jspf Banner_toolbar.jspf Banner_searchControl.jspf topNav.jspf sideNav.jspf footer.jspf Home.jsp flyout.jspf head.jspf Banner Control.jsp Default.jsp

Each kind of component is in a folder named according to the type of element that it includes: theme, screens, and skins. For example, files for the IBM theme are located under <Portal Project>/themes/html/IBM folder, Home.jsp (screen) is located at <Portal Project>/screens/html, and Control.jsp (skin) is located at <Portal Project>/skins/IBM folder if you use IBM skin. The “Layout of the portal page” section of the WebSphere Portal Information Center explains more about structure of themes, screens, and skins.

Changing theme policies

Sometimes, it is difficult to modify JSP theme files, because they include several custom tags and scripts. To make it easier, WebSphere Portal V6 introduced the Theme Policy feature, which enables you to control how a theme is rendered in a page without

changing JSP files. Moreover, by specifying different theme policies for pages, you can have different page renderings of the same theme.

(10)

Figure 8. Different appearances in an IBM theme

SideNavOnlyMinimal DoubleTopNav

SingleTopNav

If you take a look inside of theme JSP files, you will find several Theme Policy codes, which affect rendering of theme. For example, topNav.jspf file for the IBM theme has the code that Listing 1 shows.

Listing 1. topNav.jspf

<c:forEach var="i" begin="${themePolicy.topNavigationStartLevel}" end="${themePolicy.topNavigationStopLevel}" step="1">

<portal-navigation:navigation startLevel="${i}" stopLevel="${i}">

This code decides the number of rows of top navigation. If you specify 2 to

topNavigationStartLevel and 3 to topNavigationStopLevel, two rows of top

(11)

Figure 9. DoubleTopNav

The Theme Policy feature uses many other parameters to control theme rendering other than topNavigationStartLevel and topNavigationStopLevel. However, to set the values to parameters, you don’t have to modify the JSP file. The set of Theme Policy values are stored in a repository on the server, and one that is associated with a selected page is loaded dynamically at runtime. All you need to do is to set one of Theme Policy

names to a page as metadata of a content node.

There are nine theme policies predefined by WebSphere Portal V6. You can assign different theme policies to different pages. In Rational Application Developer, you can use the Properties view to change theme policies. If you would like to have two rows in the top navigation, select a label or a page in the Portal Configuration editor and specify DoubleTopNav in the Theme policy field in the Properties view.

Figure 10. Theme policies at the Properties view

2nd row 1st row

(12)

Tip:

Your own theme policy can be created and deployed to WebSphere Portal V6 by using the XML configuration interface. When you import a portal site that has your own policy by using the Import Portal Wizard, the name is added in the list of theme policies in the Properties view. You can assign it to a page. Although the policy is rendered as SingleTopNav in Rational Application Developer, after the project is deployed, the rendering will work correctly.

For more about theme policies, check the WebSphere Portal V6 Information Center.

Changing color palettes

In WebSphere Portal V6, the style sheet used in the IBM theme is dynamically generated from JSP files. Seven JSP fragment files and one style.jsp file exist under <Portal Project>/themes/IBM folder. The head.jspf file links the style.jsp file directly, and style.jsp file includes the other JSP fragment files. In WebSphere Portal V5.1, you needed to prepare several browser- and location-specific Style.css files to achieve the same appearance in any user environment. In WebSphere Portal V6, the style sheet is generated dynamically; therefore, the number of style sheet files that you have to maintain is reduced.

The Color Palette, which was introduced in WebSphere Portal V6, uses this dynamic style sheet generation. It is a set of color and graphic definitions used in the style sheet. The values are defined in the properties file by color palette. By specifying different color palettes forages, you can have color variations without changing style sheet files or JSP theme files.

(13)

Figure 11. Color variation in IBM theme

If you look inside of the JSP fragment files for the cascading style sheet (CSS), you will find several JSP expressions. For example, the selector shown in Listing 2 exists in the styles_theme.jspf file. Listing 2. styles_theme.jspf .launch { float:${requestScope.cssRules.bidiLeft}; border: 0px; color: ${colors.launchButtonText}; font-family: ${requestScope.cssRules.fontFamilySansSerifLarge}; font-size: ${requestScope.cssRules.fontSize.large}; font-weight: bold; cursor: pointer; padding-top: 4px; padding-bottom: 4px; margin-top: 0px; margin-bottom: 0px; margin-left: 0px; background: ${colors.launchButtonBackgroundImage}; background-color: ${colors.launchButtonBackground}; }

(14)

This defines the appearance of the Launch button at the top of a portal page. The values of JSP expressions starting with ${colors. are color palette values, that are loaded from the properties file at runtime. The default values are stored in the <Portal Project>/themes/html/IBM/colors/default.properties file, as Listing 3 shows. Listing 3. default.properties

# launch button which opens the navigation menu launchButtonText=#FFFFFF

launchButtonBackground=#3880DE launchButtonBackgroundImage=url(./colors/default/main_menu_background.gif) repeat-x

launchButtonHoverBackgroundImage=url(./colors/default/main_menu_background_hover.gif) repeat-x

Like theme policies, the color palette can be associated with a page in the Properties view. If you already use color palettes in your portal site, all of the names are listed in the Color palette field. Otherwise, you can create your own color palette properties file. These steps are to create a color palette named “green” and to change the breadcrumb trail color to green.

1. Select a page in the Portal Configuration editor.

2. Open the Color Palette box in the Properties view, and select Others.

3. To create a color palette named “green,” type green in the Color palette field in the Select Color Palette dialog. (See Figure 12.) If a green.properties file already exists, it will be used for green color palette. Otherwise, a

(15)

Figure 12. Select Color Palette dialog

1. Change bannerText from #3161A5 to #61A331, and save it. The crumb trail color is changed to green, as Figure 13 shows.

Figure 13. Crumb trail color

Tip:

If you would like to edit color palette values afterward, you can right-click the

Portal Configuration editor and open the Edit Style menu. The properties file for

color palette associated with current page is listed along with style sheet files used in current theme.

For more on color palettes, visit the WebSphere Portal V6 Information Center.

Changing theme JSP files

If you would like to change theme JSP files, you can use the Theme editor. The following steps change the Help icon ( ) in the banner to text, which is defined in properties, and adds Feedback, which has not been defined.

(16)

Figure 14. Toolbar

Inserting a Feedback link

1. Open the Java Resources/nls/button_en.properties file from the Project Explorer.

2. Add the following line at the bottom of the file, and then save and close it: feedback = Feedback

3. If the Autobuild option is turned off, you need to build manually.

4. In the Portal Configuration Editor, right-click, and select Edit Theme from the

drop-down menu.

5. In the Palette view for the Theme editor, expand Portal category

6. Drag the Text item from the Palette view and drop it next to the icon in the

Theme editor.

Figure 15. Dragging the feedback text

Drag and drop

7. When you see the Insert dialog, select Button for the Bundle and feedback for the

Key.

8. Select the Feedback that you inserted, and then select Insert > Insert Link from

the main menu

9. When you see the Insert Link dialog, select E-mail for Type and enter your e-mail address, such as mailto:[email protected].

10. Select the A tab in the Properties view.

11. Click the icon beside the Class field, and select Browse from the drop-down menu.

(17)

Figure 16. Properties view for the Theme editor

Changing the Help link

1. Drag the Text item from the Palette view and drop it onto the icon in the Theme

editor.

2. Delete the icon from the Theme editor.

As Figure 17 shows, you can then see the Feedback and Help links next to Log Out. Figure 17. Adding Feedback and Help

Tip: When theme JSP is opened with the Theme editor, you may see a lot of icons representing scripts and comments. If you don’t need to edit those scripts and comments, you can hide them to make your workplace cleaner by selecting Hide

(18)

Tip: The Theme editor uses the default color palette. If you would like to apply a

different color palette, select Page > Portal Status from the main menu, and change the color palette used in the theme. This won’t affect the Portal model, because this setting is used only in the Theme editor.

Test and deploy

When you complete your portal site, Rational Application Developer portal tooling enables you to test your project without deploying it to the server. If the result is good, you can deploy it back to the staging server to be ready for production. Figure 18 shows how the portal site looks in your browser.

(19)

Resources

Learn here

• Get information on IBM Rational Application Developer and how to use it: o What's new in IBM Rational Application Developer V7.0

o IBM Rational Application Developer Version 7.0 Information Center o Rational Application Developer page on IBM® developerWorks® • For product documentation for WebSphere Portal, visit the IBM WebSphere

Portal Version 6.0 Information Center

• Find out What’s new in WebSphere Portal Version 6. This developerWorks article by Stefan Hepper, Stefan Liesche, Gregory Melahn, and Thomas Stober (July 2006) describes the highlights in IBM® WebSphere® Portal Version 6.0. You see how WebSphere Portal helps you create a service-oriented architecture (SOA) environment, and you learn about the technical enhancements that speed up your development projects, providing quick business value and ease-of-use. This article is as a good starting point to understand the version content and the improvements since the previous releases.

• Read Creating a new portal, an IBM developerWorks series of articles

• Visit the Rational page on developerWorks to find technical resources and learn about best practices for the Rational Software Delivery Platform.

• Subscribe to The Rational Edge weekly newsletter. Discuss here

• Participate in the Rational Software Architect, Data Architect, Software Modeler, Systems Developer, Application Developer and Web Developer forums and the WebSphere Portal forum, where you can ask questions, share your experiences, and discuss problems and solutions.

Get products here

• Get the evaluation version of Rational Application Developer.

• Get WebSphere evaluation versions from the WebSphere downloads page.

About the author

Kenji Uchida is a software engineer at the IBM Yamato Software Lab in Japan. He has been involved in portal site development tools (Portal Designer) in Rational Application Developer V6 and V7 as a technical team lead.

Designing portal site structure and page layout using IBM Rational Application Developer V7 Part of a series on portal and portlet development