Introduction

You may be wondering how to change the logo on your portal to your company's logo. Or, maybe you want to add a left navigation pane to your portal, or change its background color. By understanding the flow of JSPs that WebSphere Portal uses to display portal pages and the contents of these JSPs, you can create or modify the themes and skins so that your portal looks like your company's Web site.

IBM WebSphere Portal Enable for Multiplatforms Version 4.2 uses various Java Server Pages (JSP), Cascading Style Sheets (CSS), and images to display portal pages. It constructs portal pages using JSPs from themes, skins, and screens directories located in C:\WebSphere\PortalServer\app\wps.ear\wps.war directory. Each of these directories contain html, wml, and chtml subdirectories, which WebSphere Portal uses to serve various clients, such as desktop browsers and mobile devices.

This is the first in a series of articles that will explain how WebSphere Portal displays a portal page using the default theme and default skin for a client accessing WebSphere Portal with Internet Explorer (IE). The rendering process is similar for all other themes and skins.

This series of articles explains:

• The flow of JSPs used to display portal pages
• How to use the JSP tags defined in engine.tld
• How to use cascading style sheet (CSS) elements
• How to use property files to display the portal title and other properties

This article describes the contents and the flow of Default.jsp, Head.jsp and ToolBarInclude.jsp defined for default theme.

Back to top

Default.jsp

The aggregation for any screen starts with the Default.jsp. The Default.jsp for the default theme is located in wp_root\app\wps.ear\wps.war\themes\html. This JSP includes other JSPs to display the title, toolbar, and to populate available places and pages. At the end of the Default.jsp the screenRender JSP tag selects the requested screen, (for example, login or forgotpassword).Figure 1 illustrates the flow of Default.jsp.

The following discussion walks you through the contents of Default.jsp. You may want to view the Default.jsp listing as you read through this discussion.

1. The Default.jsp file includes a JSP tag library engine.tld using the following URI:

   <%@ taglib uri="/WEB-INF/tld/engine.tld" prefix="wps" %>

   
   

   This tag library provides JSP tags needed to populate place names, pages, and for locating images in the requested theme and skin. You need to understand this tag library to customize your portal's look and feel.

2. To get the portal's base URL and documentation URL, constants JSP tag is used in Default.jsp. This element makes the following two scripting variables available to the page.
   
   • wpsBaseURL: Used to get the portal URL, for example, http://sukumar.ibm.com/wps/. The links for resources in wp_root\app\wps.ear\wps.war directory can be generated using this variable.
   • wpsDocURL: Used to generate link for portal help files.
3. The head portion of the html content is generated by including Head.jsp, located in the same directory as that of Default.jsp. The next section of this article describes Head.jsp.
   
4. Next, Default.jsp includes extension/PageBeginInclude.jsp. This JSP only contains comments for WebSphere Portal Enable version; its contents are not discussed here.
   
5. For all versions, Default.jsp includes the following three JSPs.
   • ToolBarInclude.jsp
   • PlaceBarInclude.jsp
   • PageBarInclude.jsp
   These JSPs are located in the same directory as that of Default.jsp. The ToolBarInclude.jsp is discussed in this article. The PlaceBarInclude.jsp and PageBarInclude.jsp files will be discussed in the next article.
   
   
6. After including the JSPs, the following link is defined.

   <a name="wpsMainContent"> </a>

   
   This link is defined just before the screenRender JSP tag. The link is referred from ToolbarInclude.jsp and contains a hidden image dot.gif. Using this link, people who listen to the page with a browser which supports speech synthesis, like Home Page Reader, can skip navigation links and go directly to listen to the contents of user customized portlets on the page. This link is needed to meet accessibility standards.
   
   
7. At this point, WebSphere Portal uses the screenRender tag to start rendering content from user customized portlets on the current page. The execution of this tag invokes JSPs from the skins and screens directories. The flow and contents of these JSPs will be discussed in future articles.
   
   
8. The Default.jsp includes extension/PageEndInclude.jsp. This JSP contains only comment for WebSphere Portal Enable version and its contents are not discussed here.
   
   

Back to top

Head.jsp

The Head.jsp generates the title and embeds links for style sheet files. It also defines variables needed for BIDI(BiDirectional) text support. The contents of this JSP are described here. You may want to view the Head.jsp listing as you read through this discussion.

• The text JSP tag lets you read a property defined by the key attribute from the file specified by the bundle attribute. The following code reads the title property from the file engine_en.properties located in C:\WebSphere\AppServer\lib\app\nls directory, for a browser accessing English as a preference. To change the title of portal pages, modify the engine_en.properties file.

  <title><wps:text key="title" bundle="nls.engine"/></title>

  
  
• The urlFindinTheme JSP tag generates the URL links for resources in the theme used by the portal. The following code generates links for style sheets specified by the file attributes.

  <link href='<wps:urlFindInTheme file="Styles.css"/>' rel="styleSheet" type="text/css"> <link href='<wps:urlFindInTheme file="HelpStyles.css"/>' rel="styleSheet" type="text/css">

  
  For English locale accessed from IE both of the files for portal styles and help styles are located in wp_root\app\wps.ear\wps.war\themes\html\ie\en.

Whenever you modify an included JSP, be sure to save Default.jsp. Otherwise, the portal displays the content from previously compiled JSPs.

Back to top

ToolBarInclude.jsp

The ToolBarInclude.jsp displays the company logo, welcome message, and a toolbar of links for the user. The toolbar of links that display on the portal are based on the user's context. For example, users who are logged in see links such as Edit Layout, Edit my profile, and Log Off; whereas, a user who is logged out sees links such as I forgot my password, Log in, and Sign up. Figure 2 shows the portal after a user has logged in to the portal.

Figure 3 shows the portal after the user has logged out.

The ToolbarInclude.jsp file displays two table rows. The first row contains two columns. The first column displays logo.gif on left side and the second column displays the toolbar of links on the right side. These columns are displayed in reverse for BIDI languages.

The second row is used as a separator between the toolbar and names of places displayed by PlaceBarInclude.jsp. It displays a stripe of back ground color using the wpsToolbar CSS element specified in Styles.css. The description for contents of this JSP are described below. You may want to view the ToolBarInclude.jsp listing as you read through this discussion.

Specifiying the company logo

A company's logo is displayed using the following code.

  <img align="absmiddle" 
    alt='<wps:text key="title" bundle="nls.engine">Portal Title</wps:text>' 
    title='<wps:text key="title" bundle="nls.engine"/>' 
    src='<wps:urlFindInTheme file="logo.gif"/>'>

For the default theme, the logo.gif file is located in the wp_root\app\wps.ear\wps.war\themes\html directory. You may change your own company's banner by either replacing logo.gif or copying your company's logo to the default theme's directory and modifying the file attribute in the code listed above. The text for the alt attribute is read from engine_en.properties file.

Link to wpsMainContent

The following code embeds a link to meet accessibility standards.

  <a href="#wpsMainContent"> 
    <img width="1" height="1" border="0" src='<%= wpsBaseURL %>/images/dot.gif' 
    alt='<wps:text key="link.skiptocontent" bundle="nls.engine"/>' 
    title='<wps:text key="link.skiptocontent" bundle="nls.engine"/>'> 
  </a>

This link allows users with disabilities to directly access content from portlets by skipping toolbar links. This link uses a very small image named dot.gif, which is not seen using a desktop browser, unless the user moves the cursor very slowly after logo.gif. The link is defined in Default.jsp which was explained earlier.

Defining the firstButton variable

The following code illustrates the firstButton JSP scripting variable.

   <% boolean firstButton = true; %>

On the top right corner of the portal page, all links and the welcome message are separated with a | delimiter. Initializing the firstButton variable to true signals WebSphere Portal not to place a | in front of the link. After generating the first link, it sets the value to false and places the | in front of all subsequent links. Figures2 and 3 show the | delimiter betweenthe toolbar links.

Executing the if JSP tag

The code fragments from the next two subsections are placed within the body of the if JSP tag.

   <wps:if loggedIn="yes" screen="Home,LoggedIn"> 
 
   <%-- Code fragment from "Displaying welcome message" subsection --%> 
   <%-- Code fragment from "Links for quick customizer" subsection --%> 
 
   </wps:if>

The body of this if JSP tag is executed only if a user is logged in and the screen is either Home or LoggedIn.

Displaying the welcome message

The following fragment reads the value of the welcome property from nls\engine_en.properties file, which has a value of Welcome {0}!.

   <wps:text key="welcome" bundle="nls.engine"> 
     <wps:textParam> 
        <wps:user attribute="givenName"/> 
     </wps:textParam> 
     <wps:textParam> 
        <wps:user attribute="familyName"/> 
     </wps:textParam> 
   </wps:text>

Figure 2, which shows the portal after the user has logged into the portal as wpsadmin,displays Welcome Wps! because Wps is the first name registered for wpsadmin. In the code above, the value of {0} is replaced with the value of the first textParam JSP tag.

Because the value of the welcome property does not contain {1}, the value of the second textParam tag is ignored. To display the last name of the user also, which is generated by the second textParam JSP tag, change the welcome property value to welcome {0} {1}!. After modifying the property file, you need to restart the portal server. The user tag allows you to use attributes givenName, familyName, or userid and returns the corresponding value.

Links for quick customizer

WebSphere Portal 4.2 introduced a new JSP tag, urlselect, which lets you create a link for specified attributes called placeName and pageName. This tag makes the link available as a scripting variable wpsSelectURL in the body of the tag. The urlselect tag is used to generate links for Edit Layout and New Page.

The following code defines the Edit Layout toolbar link.

   <wps:urlSelect placeName="Work with Pages" pageName="Edit My Pages" 
     type="editlayout"> 
 
     <% if (firstButton) { firstButton = false; } 
       else { %>&|&<% } %> 
 
    <a class="wpsToolBarLink" href='<%= wpsSelectURL %>'><wps:text 
         key="link.editlayout" bundle="nls.engine"/></a> 
   </wps:urlSelect>

The following code defines the New Page toolbar link.

    <wps:urlSelect placeName="Work with Pages" pageName="Edit My Pages" 
         type="editlayout"> 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" href='<%= wpsSelectURL %>'><wps:text 
         key="link.editlayout" bundle="nls.engine"/></a> 
    </wps:urlSelect>

You can add other links for pages using urlSelect JSP tag.

The I forgot my password link

If the user is not logged in, the link for I forgot my password is generated using the url tag. When the user clicks this link, the contents of forgotpassword.jsp located in the screens directory displays. The following code shows how to create the link for I forgot my password.

    <%-- forgot password button --%> 
    <wps:if loggedIn="no" notScreen="ForgotPassword"> 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" 
          href='<wps:url screen="ForgotPassword" 
          home="public"/>'> 
    <wps:text key="link.password" bundle="nls.engine"/></a> 
    </wps:if>

The Edit my profile link

The url tag with a command value of PrepareSelfCare generates a link for Edit my profile. Clicking on this link, displays the UserProfileForm.jsp located in the screens directory. The following code illustrates the code for displaying the link.

    <%-- selfcare button --%> 
    <wps:if loggedIn="yes" notScreen="SelfcareUserForm,SelfcareUserConf"> 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" href='<wps:url command="PrepareSelfcare" 
        reqid="no"/>'> 
    <wps:text key="link.selfcare" bundle="nls.engine"/></a> 
    </wps:if>

The Sign up link

The url tag with attribute PrepareEnrollment lets you generate a link for Sign up so that users can self enroll. Clicking on this link, displays UserProfileForm.jsp located in the screens directory. The following code shows the code to display the Sign up link.

    <wps:if loggedIn="no"> 
    <% 
    String dt = com.ibm.wps.puma.UserManager.instance().getDirectoryType(); 
    if (dt==null) 
    { 
        dt = ""; 
    } 
    if (!dt.equals("SSPM")) 
    { 
    %> 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" href='<wps:url command="PrepareEnrollment" 
        home="public" reqid="no"/>'> 
    <wps:text key="link.enrollment" bundle="nls.engine"/></a> 

You can remove the previous code from the ToolBarInclude.jsp, if you want to disable users from self enrolling into the portal.

The Help link

The Help link is generated using wpsDocURL JSP variable. This variable is available by including constants JSP tag which is explained in the Default.jsp section.

    <%-- help button --%> 
 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" href="<%= wpsDocURL %>/InfoCenter/help/index.html" 
         target="PortalHelpWindow" 
    onClick="javascript: window.open('<%= wpsDocURL %>/InfoCenter/help/index.html', 
         'PortalHelpWindow', 
    'resizable=yes,scrollbars=yes,menubar=no,toolbar=yes,status=no,width=800, 
         height=600,screenX=10,screenY=10,top=10,left=10').focus(); return false;"> 
 
    <wps:text key="link.help" bundle="nls.engine"/></a>

The Log in link

The url tag with attributes home=public and screen=Login generates the Log in link. Clicking on this link, displays login.jsp located in screens directory. You need to modify login.jsp to change the log in screen. This login.jsp uses the url tag with the attribute command=LoginUser to generate the URL for submission of credentials. The following code shows how to generate this link.

    <wps:if loggedIn="no" notScreen="Login"> 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" href='<wps:url home="public" screen="Login" 
    ssl="false"/>'><wps:text key="link.login" bundle="nls.engine"/></a> 
    </wps:if>

The Log off link

The url tag with a command attribute value of LogoutUser generates the Log off link. The following code shows how to generate this link.

    <wps:if loggedIn="yes"> 
    <% if (firstButton) { firstButton = false; } else { %>&|&<% } %> 
    <a class="wpsToolBarLink" href='<wps:url command="LogoutUser"/>'> 
    <wps:text key="link.logout" bundle="nls.engine"/></a> 
    </wps:if>

Second row

The following code displays a strip of color as a separator between the toolbar and the place bar. The color is defined as the wpsToolBarSeparator element in Styles.css. You can modify the background-color attribute of this CSS element.

    <td class="wpsToolBarSeparator" height="10" colspan="2"><img width="1" 
    height="1" border="0" src='<%= wpsBaseURL %>/images/dot.gif' alt=""> 

Conclusion

This article explained the flow of WebSphere Portal to display portal pages. The contents of Default.jsp, Head.jsp, and ToolBarInclude.jsp located in default theme directory are described. All these JSPs uses tags defined in the engine.tld file. Understanding these JSP tags and knowing how to use them in portal JSPs will help you to create new themes and to modify existing themes.

Resources

• WebSphere Portal Info Center
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Default.jsp
• Head.jsp
• ToolBarInclude.jsp
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers