Portal navigation

The themes that are shipped with WebSphere Portal provide buttons and other navigational aids to allow users to access screens (such as login, edit profile, home). The themes and skins also provide navigation to nodes in the portal hierarchy of the home screen.

The default theme also includes a page. Navigational access to pages could easily be handled by the navigation menu in the layered container.

The nodes in this hierarchy can be described by the number of levels below the content root in which they are placed. After installation, the portal themes and skins include the following JSPs to provide access to the navigation hierarchy levels.

JSP file	Navigation level	Example nodes
ToolBarInclude.jsp	1	My Portal, Administration
PlaceBarInclude.jsp	2	Welcome page under My Portal
PageBarInclude.jsp	3	My Page, under Welcome
LayeredContainer.jsp	4 and above	Nodes created by administrators and users

Navigation levels are designated by the startLevel and stopLevel attributes of the <wps:navigation/> tag. The JSPs that are provided by WebSphere Portal do not provide access to all level 1 nodes. Therefore, nodes that are created directly under content root cannot be accessed unless a JSP is included that contains <wps:navigation startLevel="1"/>. Otherwise, the <URLGeneration/> tag can be used to provide direct links. See Adding custom links to the toolbar for more information.

Create the navigation menu

The <wps:navigation/> tag is used to create the navigation menu. The content of this tag includes internal Java scriptlets that should not be modified. You can, however, customize the navigation by changing images, HTML and JSP tags, and the classes in Styles.css.

Example 1: Implementing navigation tabs

The following example shows how the navigation tag is used in PlaceBarInclude.jsp. The context of this tag is a table cell that spans the width of the portal window. This JSP provides access to level 2 nodes in the portal hierarchy, as determined by the startLevel and stopLevel attributes. The <wps:navigationLoop> tag renders its content for each of the nodes for the selected parent in level 1. The nodeInSelectionPath attribute of the <wps:if> tag is used to determine how the table cell is rendered, depending on whether the node is selected. For example, users logging in to the level 1 node, My Portal, might see a place bar with level 2 nodes, Welcome, My Work, and My Finances. This loop will render table cells for all three nodes. The nodes that are not selected will be rendered as links and the selected node will be rendered with a different background color.

<wps:navigation startLevel="2"stopLevel="2">

<wps:navigationLoop>

   <wps:if nodeInSelectionPath="yes">

      <td class="wpsSelectedPlace" nowrap height="100%">

         <a class="wpsSelectedPlaceLink" 
            href='<%=wpsNavModelUtil.createSelectionChangeURL(wpsNavNode)%>' >

            &nbsp;

            <%= com.ibm.wps.model.LocaleHelper.getTitle((com.ibm.portal.Localized)wpsNavNode, com.ibm.wps.engine.RunData.from( pageContext.getRequest()).getLocale())%>

            &nbsp;

         </a>
      </td>

   </wps:if>
                                
   <wps:if nodeInSelectionPath="no">

     <% 
         // check parameter used by Lotus WorkPlace to hide places
         ContentNode cNode = wpsNavNode.getContentNode();
                    
         boolean bShowNode = true;
                    
         if( cNode != null && cNode instanceof MetaData) {
            MetaData md = (MetaData) cNode;
            Object o = md.getValue( "hidden");
            if ( o != null && o.toString( ).equalsIgnoreCase( "Yes") ) {
               bShowNode = false;
            }
         }
                    
         if( bShowNode) {
      %>

      <td class="wpsUnSelectedPlace" nowrap height="100%">

         <a class="wpsUnSelectedPlaceLink" 
            href='<%=wpsNavModelUtil.createSelectionChangeURL(wpsNavNode)%>' >

            &nbsp;

            <%= com.ibm.wps.model.LocaleHelper.getTitle((com.ibm.portal.Localized)wpsNavNode, com.ibm.wps.engine.RunData.from( pageContext.getRequest()).getLocale()) %>

            &nbsp;
         </a>

      </td>

      <% 
      }  
      %>
   </wps:if>
</wps:navigationLoop>
</wps:navigation>

In the previous example, the code in bold must be copied as shown to customized themes. However, you can change the layout, for example, by rearranging the table tags to render each node vertically in separate table rows. You can also change the appearance, for example, by changing the colors or the place bar table row (wpsPlaceBar style class), and the background colors of each tab wpsSelectedPlace and wpsUnSelectedPlace style classes). You can also change the appearance by adding custom images.

Example 2: Customizing the navigation menu in a layered container

Users with sufficient permissions can created deeply nested nodes in the portal, which makes providing navigational access to these nodes difficult. For that reason, WebSphere Portal provides a layered container in the portal skin JSPs to allow users to access these deeply nested nodes.

To prevent the navigation menu from repeating page navigation links that are provided by theme JSPs, do not set the startLevel attribute on the <wps:navigation/> tag. If nested nodes exist for a selected page, no value causes the navigation menu to display nodes that are subordinate to the selected page and all child nodes. If nested nodes do not exist for the selected page, this value causes the navigation menu to not be displayed.

Like the theme JSPs, customizing the layered container is restricted to the HTML and JSP tags, images, and style classes.

Portal style classes

.wpsNavUnSelectedNode - Text properties for the unselected node in the tree navigation control
.wpsNavSelectedNode - Text properties for the selected node in the tree navigation control
.wpsNavLevelnum - Text properties for the nodes in the tree navigation control, nested num levels deep. For example, wpsNavLevel4 would define the look and feel of the fourth level nodes that are listed in the tree. If this class is not defined for a level, the portal server uses its own definition.
.wpsNavExpandCollapseIcon - Width and height of the expand and collapse icons in the navigation menu

Images

NavigationExpanded.gif - Image used for an expanded node. This image has a corresponding NavigationExpanded_rtl.gif image that is used by bidirectional languages.
NavigationCollapsed.gif - Image used for a collapsed node. This image has a corresponding NavigationCollapsed_rtl.gif image that is used by bidirectional languages.

The following example shows the tag portion of the <wps:navigationLoop> section from LayeredContainer-V.jsp. There are still some Java code snippets in this section, which should not be modified.


<wps:navigationLoop>
   <%

   ...
   // Java code omitted

   %>
   <tr>
      <td class="<%= rowCssClass %>">
         <table border="0" cellpadding="0" cellspacing="0">
            <tr>
               <% for (int i=wpsNavLevel.intValue(); i > 1; i--) {%>
                     <td width="1">&nbsp;&nbsp;&nbsp;&nbsp;</td>
               <% } %>
               <td class="<%= rowCssClass %>" width="14" valign="top">
                  <%
                     if(nodeHasChildren)
                     {
                        //if(wpsNavModel.isExpanded(wpsNavNode))
                        if( ((Boolean)((com.ibm.portal.state.StateModel)wpsNavModel).getState(wpsNavNode, 
                                                      com.ibm.portal.state.StateType.EXPANSION)).booleanValue() )
                        {
                  %>
                     <a href="<%=wpsNavModelUtil.createStateChangeURL(wpsNavNode, 
                                                      com.ibm.portal.state.StateType.EXPANSION, new Boolean(false))%>" 
                        border="0">
                        <img alt='<wps:text key="link.collapse" bundle="nls.engine"/>' 
                             border="0" 
                             class="wpsNavExpandCollapseIcon" 
                             src="<wps:urlFindInTheme file='<%="NavigationExpanded" + bidiImageRTL + ".gif"%>' />">
                     </a>
                  <%
                     }
                        else
                     {
                  %>
                     <a href="<%=wpsNavModelUtil.createStateChangeURL(wpsNavNode, 
                                                      com.ibm.portal.state.StateType.EXPANSION, new Boolean(true))%>" 
                        border="0">
                        <img alt='<wps:text key="link.expand" bundle="nls.engine"/>' 
                             border="0" 
                             class="wpsNavExpandCollapseIcon" 
                             src="<wps:urlFindInTheme file='<%="NavigationCollapsed" + bidiImageRTL + ".gif"%>' />">
                     </a>
                  <%
                        }
                     }
                     else
                     {
                  %>
                     <img alt="" border="0" class="wpsNavExpandCollapseIcon" src='<%=wpsBaseURL%>/images/dot.gif'>
                  <%
                        }
                  %>
               </td>
               <td class="<%= rowCssClass %>">
                                        
                  <% if (selectURL != null) { %>
                     <a class="<%= rowCssClass %>" 
                        href="<%=selectURL%>" 
                        <% /* if the node type is URL, use target attribute to launch a new window */ %>
                        <% if (com.ibm.portal.content.ContentNodeType.EXTERNALURL.equals(wpsNavNode.getContentNode().getContentNodeType())) 
                           {%>
                              target="_blank"
                           <% } %> >
                  <% } %>
                                            
                  <span class="wpsNavLevel<%=wpsNavLevel%>">
                                            
                  <% if (appendNameToTitle) { %>
                     <wps:text key="title.admin.name.composition" bundle="nls.engine">
                        <wps:textParam><%= nodeTitle %></wps:textParam>
                        <wps:textParam><%= nodeName %></wps:textParam>
                     </wps:text>
                  <% } else { %>
                     <%= nodeTitle %>
                  <% } %>
                                            
                  </span>
                                            
                  <% if (selectURL != null) { %>
                     </a>
                  <% } %>
               </td>
            </tr>
         </table>
      </td>
   </tr>
</wps:navigationLoop>

Only one copy of the layered container should exist in the /skins directory, rather than multiple copies for different skins. Therefore, it is better to save a backup copy of the layered container JSP before making modifications to the active JSP.

Adding custom links to the toolbar

Use the <wps:URLGeneration/> tag to create links to pages from anywhere in the portal. See the description of this tag for more information about attributes.

The following steps show how to add a custom page link to one of the theme JSPs. The steps use one of the pages provided by WebSphere Portal, which is set up with a custom unique name during installation. Use the same steps for creating links to new nodes that you have created, but also add a custom unique name to that node.