Comments
Description
Transcript
Variations on a portal theme
Variations on a portal theme Four case studies in customizing WebSphere Portal Velda Bartek, User Experience Designer, IBM Raleigh Lab Alan Booth, Software Developer, IBM Raleigh Lab Patrick McGowan, Product Designer, IBM Raleigh Lab February, 2005 © Copyright International Business Machines Corporation 2005. All rights reserved. This article describes, and provides as a download, several examples of themes and skins for WebSphere Portal. You can use these examples to understand how WebSphere Portal applies skins and themes in the assembly of portal pages. You can also use the examples to help you customize your own portal elements. 1 Table of contents Introduction ......................................................................................................................... 2 About the samples ............................................................................................................... 3 Sample theme: Container explainer ................................................................................ 3 Description .................................................................................................................. 3 Understanding the container explainer files................................................................ 5 Using the container explainer code ............................................................................. 6 Sample theme: Left and right navigation ........................................................................ 6 Description .................................................................................................................. 6 Examining the navigation code ................................................................................... 7 Using the navigation sample code............................................................................... 9 Sample theme: Crumb trail ............................................................................................. 9 Description .................................................................................................................. 9 Examining the crumb trail code ................................................................................ 11 Using the crumb trail sample code............................................................................ 12 Sample skin: Resizable portlet ...................................................................................... 13 Description ................................................................................................................ 13 Examining the resizable portlet code ........................................................................ 15 Using the resizable portlet sample code.................................................................... 18 Conclusion......................................................................................................................... 18 Resources .......................................................................................................................... 18 Download .......................................................................................................................... 19 About the authors .............................................................................................................. 19 Introduction Creating a new portal requires different types of skills, usually provided by multiple team members. The user interface developer creates the interface design and implements the design for a specific portal instance. The developer creates portal page layouts, develops custom themes and skins, and assigns these elements to the portal. The developer might use a tool to create mockups of designs and to create the page layout, theme, and skin code. In WebSphere Portal, the portal’s themes and skins provide its branding and overall user experience elements. These elements are defined in a set of JSPs, Cascading Style Sheets (CSS), and images. You can easily change the branding and overall look and feel by replacing or augmenting the themes and skins associated with your portal. Themes control the look and feel of the portal, including the structure and location of portal components, navigation, and images. Skins define the visual appearance of a portlet, including its title bar and frame. 2 This article describes several themes and skins that you can use to start creating your own themes and skins. To get the most use from these samples, you should have some experience designing user experience, using HTML and JSPs, and customizing portal themes and skin JSPs. About the samples The samples are provided in a download. As you work with these samples, place the themes and skins in the directory structure as described below for each sample. The sample themes and skins show you: • • • How the components of a portal page relate to each other and how they form the portal page, from various JSPs. How to provide breadcrumb trails within a portal to assist visitors in learning and recalling how they traversed to a particular portlet. How to incorporate content and business logic into a skin. Sample theme: Container explainer The first sample, the container explainer, shows you how the various files and portal page elements lay out, or are aggregated on, a portal page. Description The container explainer shows how constituent elements of a portal page come together from the JSPs, by calling out the theme, screen, and skin elements. You see labels for each element laid out in the table cells that make up the page. This sample helps you understand how containers and rows interact with layer containers. Containers are used to define page layout and are used to aggregate child containers. Just looking at a portal page, such as the page shown in Figure 1, it is not easy to locate the containers on the page. 3 Figure 1. A portal page Using the container explainer tools, you can locate the following containers, as shown in Figure 2: • The aggregation of the theme begins with Default.jsp. It includes other JSPs to display the title and toolbar, and to populate available places and pages. By default, Layered-Container.jsp starts to render where the theme left off. We recommend putting logic in the theme, where other structures are included, rather than in Layered-Container.jsp. • PlaceBarInclude.jsp is the top level navigation in this design. It populates names of places and displays the Favorites list box. • PageBarInclude.jsp is the secondary navigation in this design; that is, it is the navigation for the page. You can use it to display Previous and Next links. • Unlayered-Container-H.jsp is the container for each row and is used by portal customization to arrange portlets within the page. • Unlayered-Container-V.jsp is the container for each column and is used by portal customization to arrange portlets within the page. As shown in Figure 2, there are two Unlayered-Container-V.jsp containers on this page. • Control.jsp defines the portlet skin. 4 Figure 2. The portal page with its containers displayed Understanding the container explainer files Use ThemeExplainer.zip and SkinExplainer.zip in the download, to understand how themes and skins are constructed and in creating your own themes and skins. The ThemeExplainer.zip contains the theme for the container explainer; the SkinExplainer.zip contains a skin. You can use these to show your portal page containers displayed in a manner similar to those shown in Figure 2. You might also find this sample is helpful in debugging any problems that occur as you create your own themes, skins, and portal. For example, suppose the navigation tabs are not rendering correctly. You know there is in a mistake in the table structure that defines the navigation tabs in the theme. Container explainer can help you determine which JSP contains the mistake. Here are a few additional tips: • • • When working with a theme and previewing changes in the portal, don’t forget to touch Default.jsp. Turn table borders On to see where you are working. Theme and Skin JSPs are not recompiled by default. If you change the JSPs and do not see the updates immediately, you probably need to enable JSP reloading. Please see the WebSphere Portal InfoCenter for more information on how to enable automatic JSP Reloading. 5 Using the container explainer code Place the sample files in the themes and skins directories within the WebSphere Portal Web application in the Application Server's installation directory. This can vary based on the customer configuration. Usually it will be something like: <AppServer>\installedApps\<Node Name>\wps.ear\wps.war\skins 1. Unzip and copy the skin files to a directory, such as skins\html\SkinExplainer. 2. Register the SkinExplainer skin with the server using the Themes & Skins portlet. 3. Unzip and copy the ThemeExplainer theme files to a directory themes\html\ThemeExplainer. 4. Register the theme with the server, using the Themes & Skins portlet. 5. Register the SkinExplainer skin as the default skin for the ThemeExplainer theme. 6. Create a test page and assign the ThemeExplainer theme to that page. Sample theme: Left and right navigation The left and right navigation sample illustrates how to create standard left and right Web page navigation in a portal. Description The portal page shown in Figure 3 has two navigation areas – one on the left, the other on the right. This theme’s LayeredContainer.jsp contains the statements which implement these navigation areas. You could use this sample to keep the visual appearance and navigation interaction consistent for your site’s visitors as your site transitions from Web pages to a portal. As you develop your themes, consider using the Web Services for Remote Portlets (WSRP) style classes consistently in all themes. Most of these WSRP styles are included in the WebSphere Portal V5.0 Styles.css. Part of the WSRP industry standard defines a set of style classes. By writing your portlets so that they use these style classes, you enable a remote portlet, when consumed in another portal, to inherit the look and feel defined by the consuming portal. For example, consider the WSRP style class which defines the look and feel of field labels, called portlet-field-label. (All WSRP styles follow the syntax portlet-*; the non-WSRP styles in the WebSphere Portal CSS follow the wps.* syntax). Suppose that company A writes a portlet and the field labels are created using the portlet- 6 field-label style. Company B defines that field labels are blue, bold, and 12pt Verdana. When company B consumes the company A portlet, its field labels will use blue, bold, and 12pt Verdana. The WSRP standard was released shortly after WebSphere Portal 5.0 was released. Therefore, WebSphere Portal was only able to include the style names that were being considered for the standard, which turned out to be the majority of styles that are in the standard. A couple more class names were introduced after V5.0 shipped. WebSphere Portal supports these, in that, you can add these styles to your CSS if you want to work with WSRP portlets; WebSphere Portal will not prevent you from using them. As you create your themes, avoid creating new proprietary classes using the WSRP style syntax of portlet-* (for example, portlet-form-field-label); otherwise, you would restrict other applications from consuming the Web services you provide. Figure 3. A portal page with primary (left-side) and secondary (right-side) navigation Examining the navigation code The code for this example is in the LayeredContainer.zip file, in the download. To get the most out of this section, open LayeredContainer.jsp, and follow along with this discussion. 7 To create the navigation areas, the LayeredContainer.jsp code uses the wps:navigation and wps:navigationLoop tags. The contents of the wps:navigation tag include internal Java scriptlets. Change the appearance of the navigation by changing the images, JSP and HTML tags, and classes in Styles.css. Because there are two navigation areas, the navigation tags, wps:navigation and wps:navigationLoop are used twice. The first wps:navigation tag, on line 19 in the sample LayeredContainer.jsp, specifies the left navigation area. Using the wps:navigation tag makes the wpsNavModel scripting variable available. This variable is used in the body tag to render the navigation nodes. Listing 1. LayeredContainer.jsp, beginning with line 19 <wps:navigation stopLevel="4"> <wps:navigationLoop> <%-- Left Navigation Here --%> </wps:navigationLoop> </wps:navigation> <wps:compositionRender> <%-- Portlets go here --%> </wps:compositionRender> <wps:navigation> <wps:navigationLoop> <%-- Right Navigation Here --%> </wps:navigationLoop> </wps:navigation> The wps:navigation tag iterates through a subset of the pages in the portal. The contents of the subset are based on several factors: user permissions, user customizations, and the initialization parameters that the tag is called with. The stopLevel and startLevel values define the levels of the current navigation tree. This is the way that WebSphere Portal maps a two-dimensional navigation tree traversal into a onedimensional iteration. The stopLevel attribute of the wps:navigation tag in Listing 1 indicates that only four levels of navigation will display. The startLevel attribute is not used; therefore, the navigation menu does not repeat page navigation links that are provided by theme JSPs. The wps:navigation and stopLevel attribute are in bold red text in the distillation of LayeredContainer.jsp shown in Listing 1. The second wps:navigation tag (line 178 in the sample JSP file) specifies the navigation area on the right. 8 The wps:navigationLoop tags identify the markup that is used for each navigation node. The wps:navigationLoop cycles through navigation nodes (wpsNavNode) and children. You can locate these tags at line 25 (left navigation) and line 184 (right navigation) in the LayeredContainer.jsp. Using the navigation sample code 1. Edit the LayeredContainer.jsp for the default skin. The default skin for the theme is assigned in the Themes & Skins portlet. Most skins do not define a LayeredContainer.jsp. When this is the case, the WebSphere Portal engine looks in the parent directory and uses the LayeredContainer.jsp from there. By default, in versions of WebSphere Portal prior to V5, the site navigation is defined in the LayeredContainer.jsp. 2. The navigation is inserted on the left side of the page because the navigation logic precedes the call to the <wps:compositionRender> tag. By simply moving the logic past this tag, you enable the navigation on the right side of the page. If you copy the logic and put it in both places, the navigation can be split between the sides. 3. Depending on the depth of your navigation tree, you may want to manipulate the startLevel and stopLevel attributes on the <wps:navigation> tag. You can adjust the amount of navigation shown in each portion of the navigation by manipulating these values. Sample theme: Crumb trail When re-designing and migrating existing intranet or Internet Web sites into a portal, a designer is confronted with how to maintain some of the behaviors and appearance of the existing Web pages. The crumb trail is one way to maintain a behavior which site visitors are familiar with. You might say: “Our site has a breadcrumb trail. How do I implement a trail in a portal?” This sample shows you how. Description The crumb trail sample theme presents the user a concrete view of how he or she navigated to the current content displayed on the portal page. This trail removes the need for the user to learn and recall how he traversed to this location. The trail is built as the user navigates through the portal. Because the crumb trail behaves in a manner similar to Web site breadcrumb trails, it builds on the user’s existing model. The user can also quickly navigate to a previous page by clicking on one of the trail elements rather than scrolling around in the navigation area. 9 As shown in Figure 4, the user is working on his e-mail. The crumb trail above the email portlet indicates that the user first accessed My Portal, then My Work, and finally Email navigation elements to arrive at this page. Figure 4. Crumb trail to the e-mail page From e-mail, to access the sub page on the Productivity set of pages, the user selects Productivity in the secondary navigation layer as shown in Figure 5. Figure 5. Working with Productivity tools 10 The user then selects Subpage on the Productivity home page, as indicated in the crumb trail in Figure 6. Figure 6. Drilling down to the Productivity Subpage Examining the crumb trail code The code for this example is in the CrumbTrailInclude.zip file, in the download. To get the most out of this section, open CrumbTrailInclude.jsp, and follow along with this discussion. To create the crumb trail that displays the current navigation path of a page, include the CrumbTrail.jsp code in one of your themes. It steps through the current navigation and outputs all currently selected navigation nodes. The line depicted in bold red text specifies the contents of the crumb trail that is displayed on the portal page. Listing 2. From CrumbTrail.jsp <wps:if navigationAvailable="yes" screen="Home,LoggedIn,LoggedOut,ErrorNotAuthorized"> <table border="0" cellspacing="0" cellpadding="0" width="100%"> <tr> <td class="wpsPageBar" valign="top" align="<%=bidiAlignLeft%>", nowrap> <table border="0" cellspacing="0" cellpadding="0"> <tr> <wps:navigation startLevel="0"> <td class="wpsSelectedPage" nowrap> <wps:navigationLoop> <wps:if nodeInSelectionPath="yes"> 11 <a class="wpsSelectedPageLink" href='<%=wpsNavModelUtil.createSelectionChangeURL(wpsNavNode)%>' > <%= com.ibm.wps.model.LocaleHelper.getTitle((com.ibm.portal.Localized) wpsNavNode, com.ibm.wps.engine.RunData.from( pageContext.getRequest()).getLocale())%> -> </a> </wps:if> </wps:navigationLoop> </td> </wps:navigation> </tr> </table> </td> </tr> </table> </wps:if> The column on the left in Figure 6 is there because of how the CrumbTrail.jsp is written. Either the LayeredContainer.jsp from the skin (if you are using WebSphere Portal V5.0) or the NavigationTreeInclude.jsp (WebSphere Portal V5.1) inserts the column on the page. The navigation is called in several places on the aggregated JSP: the place bar, the page bar, the left navigation, and now, the crumb trail. These navigation sections cooperate by setting a flag that indicates the depth of navigation in the previous navigation section. The behavior can be adjusted by the startLevel and stopLevel attributes on the wps:navigation tag. Because the crumb trail does not have a stopLevel, the LayeredContainer thinks that it should start over and redo the entire navigation. To fix this, you need to either alter the stopLevel in the crumb trail or alter the depth of the nodes in this navigation sub tree. The CrumbTrail.jsp code alters the depth of the nodes in the navigation sub tree. Using the crumb trail sample code To add the crumb trail to an existing theme: 1. Edit the Default.jsp for the theme that you want to use a crumb trail. This theme might be any of several other JSPs that are statically included from Default.jsp. See the ContainerExplainer example for more details on how the JSPs fit together. 2. Add JSP code to include the CrumbTrailInclude.jsp in the appropriate place in your theme. <%@ include file="../CrumbTrailInclude.jsp" %> 3. If you do not have JSP reloading enabled for the WPS Web application, you will need to restart the portal server. If JSP reloading is enabled, simply refresh your page and you see your changes reflected immediately. 12 Sample skin: Resizable portlet The resizable portlet sample illustrates how a user interface control can be placed in a skin. This content spot can be used to trigger the execution of business logic that in turn enables enriched support for users. Description A skin is the JSP and graphics that determine, in conjunction with a theme, the look and feel surrounding a portlet on a page. A skin may be defined such that it always looks the same regardless of the theme. Or, a skin may be defined to change and adapt with different themes. Themes may have one or more associated skins or a default skin. A skin is a J2EE servlet and as such can include business logic. You could place a content spot in the skin that, when selected, could query a workflow engine and have it inform the person that work is waiting. All themes and skins share the same HTTP Session and Request objects from the main portal servlet. Messages are stored in a theme session and pass to portlets on the portlet request. For example, in WebSphere Portal v5, when editing a page, the context of the page being edited is passed between the content (the portlet), the appearance (skin), and locks (permissions). This resizable portlet skin is an example of working with an HTTP session illustrating how to capture information and use it on a subsequent request. The information in this instance is the user-selection of either the increase or decrease portlet size icons. As shown in Figure 7, the user can select the decorations in the skin border to enable the Bookmarks portlet’s size to incrementally increase and decrease within the column on the portal page. Figure 7. Bookmarks portlet 13 Selecting the increase decoration, the user sees the Bookmarks portlet expand as shown in Figure 8. 14 Figure 8. Expanded Bookmarks portlet You could extend this sample to provide draggable support by writing HTML code. Examining the resizable portlet code The code for this example is in the ResizeSkin.zip file, in the download. To get the most out of this section, open Control.jsp, and follow along with this discussion. Use the Control.jsp code to create a new skin JSP that allows portlet windows to be resized. The highlighted code red text indicates where this Control.jsp differs from the default Control.jsp shipped with WebSphere Portal. Links are added to the portlet window. When the user clicks on a link, the window is either made wider or narrower. JavaScript function is executed and the window is resized. Listing 3. From Control.jsp <%@ page session="true" buffer="none" %> width --%> <%-- Use session to store 15 <% /* @copyright jsp */ %> <%@ taglib uri="/WEB-INF/tld/engine.tld" prefix="wps" %> <%@ include file="../BidiInclude.jsp" %> <wps:constants/> <a name="<wps:portletID/>"></a> <% String borderColor="#CFD9E5"; String tableHeight = ""; %> <wps:if portletState="Normal,Maximized,Solo"> <% tableHeight = "height=\"100%\""; %> </wps:if> <% int tableWidth = 250; String s_width = (String)session.getAttribute("width"); if (s_width != null) { try { int i = Integer.parseInt(s_width); tableWidth = i; } catch (Exception e) { } } String adjustWidth = (String)request.getParameter("adjustWidth"); if (adjustWidth != null) { if (adjustWidth.equals("wider")) { tableWidth += 50; } if (adjustWidth.equals("narrower")) { tableWidth -= 50; } session.setAttribute("width",Integer.toString(tableWidth)); } %> <table border="0" width="<%=tableWidth%>" <%=tableHeight%> cellpadding="0" cellspacing="5"> <tr> <td> <table border="0" width="100%" <%=tableHeight%> cellpadding="0" cellspacing="0" class="wpsPortletBody"> <%-- <tr height="1"> <td bgcolor="<%=borderColor%>" width="1" height="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> <td bgcolor="<%=borderColor%>" height="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> 16 <td bgcolor="<%=borderColor%>" width="1" height="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> </tr> --%> <!-- Skin header --> <tr height="1"> <!-- left border --> <td border="0" bgcolor="<%=borderColor%>" width="1" height="12"><img alt="" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> <%-- old: <td width="100%" height="12" nowrap>--%> <td width="100%" nowrap> <table border="0" width="100%" cellpadding="3" cellspacing="0"> <tr> <td class="wpsPortletTitle" width="100%" nowrap align="<%= bidiAlignLeft %>" valign="middle"> <wps:portletTitle> <wps:problem bundle="nls.problem"/> </wps:portletTitle> <img alt="" border="0" width="1" height="12" align="absmiddle" src='<wps:urlFindInTheme file="title_minheight.gif"/>'> </td> <%@ include file="../ShowTools.jsp" %> … <!-- portlet body --> <wps:if portletState="Normal,Maximized,Solo"> <tr height="100%"> <td bgcolor="<%=borderColor%>" height="100%" width="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> <td width="100%" valign="top"> <table width="100%" height="100%" border="0" cellpadding="5" cellspacing="0"> <tr> <td <wps:bidi dir="ltr" attribute="portlet">dir="ltr"</wps:bidi> valign="top"> <div width="100%"> <wps:portletRender> <font COLOR="red"><wps:problem bundle="nls.problem"/></font> </wps:portletRender> </div> </td> </tr> </table> </td> <td bgcolor="<%=borderColor%>" width="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'> <a href="?adjustWidth=wider"><img border="0" align="absmiddle" class="wpsPortletTitleIcon" src="<wps:urlFindInTheme file='<%= "title_back_rtl.gif" %>'/>" alt="Wider"></a> <a href="?adjustWidth=narrower"><img border="0" align="absmiddle" class="wpsPortletTitleIcon" src="<wps:urlFindInTheme file='<%= "title_back.gif" %>'/>" alt="Narrower"></a> </td> </tr> </wps:if> <!-- bottom border --> <tr height="1"> 17 <td bgcolor="<%=borderColor%>" width="1" height="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> <td bgcolor="<%=borderColor%>" height="1"><img alt="" border="0" width="1" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> <td bgcolor="<%=borderColor%>" width="1" height="1"><img alt="" border="0" width="0" height="1" src='<%=wpsBaseURL%>/images/dot.gif'></td> </tr> </table> </td> </tr> </table> Using the resizable portlet sample code 1. Copy the skin files to a directory skins\html\ResizeSkin. 2. Register the skin with the server using the Themes & Skins portlet. 3. Add the skin to one or more themes using the Themes & Skins portlet. 4. Create a test page that is using a theme that allows the user of the ResizeSkin. Add a portlet to the page using the Page Manager and Content Layout portlets. 5. Assign one of the themes that allows the ResizeSkin (from step 3) to this test page. 6. Use the Appearance portlet to set the skin on the test portlet that you added to the page. Conclusion You can expand the interaction model and capabilities of your portal by building your own themes and skins. You can use the container explainer sample to assist you in building your themes and to help debug problems with themes. Apply the navigation and breadcrumb samples to comply with corporate design and Web content rules. Extend the resizable portlet sample to add business logic into your portlets, using the HTTP session to capture information to be used on a subsequent request. With these new tools, you can go out and tackle a portal improvement project today. Resources • Creating a Distinctive Look and Feel for Your Portal http://www.ibm.com/developerworks/websphere/library/techarticles/0307_bartek/bart ek.html 18 • Mastering IBM WebSphere Portal: Expert Guidance to Build and Deploy Portal Applications, by Ron Ben-Natan, Richard Gornitsky, Tim Hanis, and Ori Sasson ISBN: 0764539914 • Understanding How WebSphere Portal Displays Portal Pages Using the Default Theme -- Part 2: Describing PlaceBarInclude.jsp and PageBarInclude.jsp http://www.ibm.com/developerworks/websphere/library/techarticles/0307_konduru/0 307_konduru.html • Understanding How WebSphere Portal Displays Portal Pages - Part 1: Default.jsp, Head.jsp, and ToolBarInclude.jsp http://www.ibm.com/developerworks/websphere/library/techarticles/0304_konduru/0 304_konduru.html • WebSphere Portal V5 product documentation http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html • WebSphere Portal Developers Guide V5.0 http://publib.boulder.ibm.com/pvc/wp/500/ent/en/InfoCenter/wpf-dev-ent.pdf • WebSphere Portal zone http:/www.ibm.com/developerworks/websphere/zones/portal/ Download To download the code for the sample application, see the cover page for this article: http://www.ibm.com/developerworks/websphere/library/techarticles/0501_bartek/0501_b artek.html. About the authors Velda Bartek is a user experience designer for IBM. She works with customers and interface designers developing WebSphere products to ensure the products are easy to use. You can reach Velda at [email protected]. Alan Booth is a software developer currently working on the WebSphere Portal. Alan is passionate about software quality and usability. You can reach Alan at [email protected]. Patrick McGowan is a product design lead for IBM Lotus Software. He designs the systems, features, functions, and interfaces. You can reach Patrick at [email protected]. 19 Trademarks • • • • DB2, IBM, Lotus, Tivoli, Rational, and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml 20