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
Designing portal site structure and page layout, Page 2 of 19 Contents Abstract... 3 Introduction... 3 Create a portal project... 3 Define page structure... 4 Portal models... 4 Defining page layout... 5 Inserting content nodes... 5 Inserting portlets... 6 Adding a page to Quick Links... 7 Customize the look and feel of your portal page... 8 Theme JSP structure... 8 Changing theme policies... 9 Changing color palettes... 12 Changing theme JSP files... 15 Inserting a Feedback link... 16 Changing the Help link... 17 Test and deploy... 18 Other articles in this series... 19 Resources... 19 About the author... 19
Designing portal site structure and page layout, Page 3 of 19 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
Designing portal site structure and page layout, Page 4 of 19 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 Deployment Descriptor Java resources folder PortalConfiguration folder Portal Configuration editor PortalContent folder Skins Themes Description Shortcut to the PortalContent/WEB-INF/web.xml file. Usually, you don t have to modify it. 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. Folder containing ibm-portal-topology.xml file, which is a portal configuration model. Shortcut to the <Portal Project>/PortalConfiguration/ibm-portaltopology.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. 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. 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. Shortcuts to themes installed into your portal site. By doubleclicking 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.
Designing portal site structure and page layout, Page 5 of 19 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
Designing portal site structure and page layout, Page 6 of 19 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 Drag and drop 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 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
Designing portal site structure and page layout, Page 7 of 19 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.
Designing portal site structure and page layout, Page 8 of 19 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 of your portal page Theme JSP structure A theme defines look and feel of a portal site. It consists of several resources, such asjava Server Pages (JSP), CSS, image, and properties files. In most cases, 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 named IBM. Figure 6 shows the composition of the IBM theme. Figure 6. Theme structure Banner Top navigation Side navigation Screen Footer The IBM theme consists of components. Basically, each component is described by a JSP fragment file, which is included directly or indirectly from the Default.jsp file, and some of them include other JSP fragment files. Figure 7 shows the hierarchy of JSP and JSP fragment files used in the theme.
Designing portal site structure and page layout, Page 9 of 19 Figure 7. Hierarchy of the IBM theme JSP files Default.jsp head.jspf banner.jspf Banner_crumbtrail.jspf Banner_toolbar.jspf Banner Banner_searchControl.jspf topnav.jspf sidenav.jspf Top Navigation Side Navigation Home.jsp footer.jspf flyout.jspf Control.jsp Screen Footer 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.
Designing portal site structure and page layout, Page 10 of 19 Figure 8. Different appearances in an IBM theme SingleTopNav SideNavOnlyMinimal DoubleTopNav 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 navigation show up, as Figure 9 illustrates.
Designing portal site structure and page layout, Page 11 of 19 Figure 9. DoubleTopNav 1st row 2nd row 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
Designing portal site structure and page layout, Page 12 of 19 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.
Designing portal site structure and page layout, Page 13 of 19 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};
Designing portal site structure and page layout, Page 14 of 19 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 green.properties file is created, based on the default.properties file.
Designing portal site structure and page layout, Page 15 of 19 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.
Designing portal site structure and page layout, Page 16 of 19 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:yourid@your.domain. 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. 12. Select toolbarlink in the Select Class dialog.
Designing portal site structure and page layout, Page 17 of 19 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 All from toolbar menu.
Designing portal site structure and page layout, Page 18 of 19 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. Figure 18. Finish
Designing portal site structure and page layout, Page 19 of 19 Other articles in this series Check the One-stop guide to portal and portlet application development using Rational Application Developer V7 and WebSphere Portal V6 for summaries of the nine other articles in this series and links to download each of them in PDF format. Topics covered include the predevelopment resources, portlet tooling features, portal design tools, and the testing, deploying, and debugging capabilities of Rational Application Developer. 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.