WebSphere Portal: Implement a navigation tree

 

+
Search Tips   |   Advanced Search

 

---

Overview

Users with sufficient permissions can create deeply nested nodes in the portal, which makes providing navigational access to these nodes difficult. For that reason, WebSphere Portal provides a navigation tree, NavigationTreeInclude.jsp, which allows users to access these deeply nested nodes.

The following example shows the visual elements of the navigation tree as they might be rendered in the browser.

Main   Chapter One   Chapter Two   Section One   Section Two   Chapter Three   Section One   Section Two   Chapter Four

With this example, assume that a place bar (level 2 navigation) and a page bar (level 3 navigation) have already been rendered. The navigation tree shows a that only one level 4 node exists, Main, for the selected level 3 node.   There are four level 5 nodes. Chapter One and Chapter Four are collapsed and Chapter Two and Chapter Three are expanded.   Section One under Chapter Three is selected. Style definitions for the wpsNavSelectedNode class provide visual indications that this node is selected. The background color is different and the text is stronger.   The selection path includes three nodes in this illustration: Main, Chapter Three, and Section One. The selected level 2 and 3 nodes are also part of the selection path, even though they are not shown.

NavigationTreeInclude.jsp includes scriptlets that include internal Java code. Manipulation of this code is not supported. However, you can customize the appearance of the navigation tree by providing your own custom HTML markup, images, and style class definitions. You can also introduce any portal JSP tags that are supported for navigation. The following are some of the visual elements that you can modify.

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 navigation tree, 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.
• NavigationCollapsed.gif - Image used for a collapsed node.

You should already be familiar with the structure of a single level navigation before you start working with the navigation tree. See Implementing a single level of navigation for more information. The following sections describe the elements of the navigation tree.

• Structured outline for the navigation tree
• Import statements
• Navigation loop variables
• Navigation link
• Expand/collapse markup
• Indentation markup
• Customization tools

 

Structured outline for the navigation tree

The structured outline for a navigation tree is similar to the structure for a single layer navigation.

<%-- Import statements --%>

<%-- Start of navigation tree --%>
<wps:if navigationAvailable="yes" screen="Home,LoggedIn,LoggedOut,ErrorNotAuthorized">

<wps:navigation>                                         
     <wps:navigationLoop>                                  
                                                           
       <%-- Indentation markup --%>                        
                                                           
       <%-- Navigation loop variable declarations --%>     
                                                           
       <%-- Expand/collapse markup --%>                    
                                                           
       <%-- Navigation link --%>                           
          <%-- Customization tools --%>                    
                                                           
     </wps:navigationLoop>                                 
  </wps:navigation>                                        

</wps:if>
<%-- End of navigation level x --%>

To prevent the navigation tree from repeating page navigation links that are already rendered, do not set the startLevel attribute on the <wps:navigation/> tag. When the startLevel attribute is not set, the navigation tree is rendered as follows:

• If subordinate nodes exist for a selected node, the navigation tree is displayed with nodes subordinate to the selected node, as well as all child nodes.

• If nested nodes do not exist for the selected page, the navigation tree is not displayed.

The <wps:navigation/> and <wps:navigationLoop/> tags makes several scripting variables available for obtaining information for the navigation.

• wpsNavNode contains information about the current navigation node, for example, whether the node type is a page or a label.

• wpsSelectionModel describes every element in the selection path, from the content root to the currently selected node.

• wpsNavModel represents the current navigation model, which describes the topology of the navigation visible to the current user.

• wpsNavNodeUtil is a utility class for generating URLs to change the expansion state of the node in the navigation tree.

• wpsNavTreeLevel is an Integer for the current navigation level of the node relative to the top of the navigation tree (content root).

• wpsNavLevel is an Integer for the current navigation level of the node relative to the start level.

These variables are used to access methods that are part of an internal API which is not available for public use, except when used exactly as shown in NavigationTreeInclude.jsp.

 

Import statements

The following packages are required by the navigation tree.

import statements
<%@ page import="java.util.*" %>
<%@ page import="java.text.*" %>
<%@ page import="com.ibm.portal.content.ContentNodeType,
                 com.ibm.wps.portlets.admin.AdminPortletUtils, 
                 com.ibm.wps.util.CreateUrlCommand, 
                 com.ibm.wps.portlets.admin.shared.*"%>

 

Navigation loop variables

The following variables are declared at the beginning of the navigation loop, and hence, evaluated for each node in the navigation tree.

 

rowCssClass

String used as one of the following value of the style class for the node:

• wpsNavSelectedNode: variable is set to this String if the node is selected.
• wpsNavUnSelectedNode: variable is set to this String if the node is not selected.
• wpsNavUnSelectableNode: variable is set to this String if the node cannot be selected ( node is a label )

selectURL

String used for the URL for the node or null if the node is not selectable (label)

nodeTitle

String that holds the title of the node, can be replaced by <wps:title/> tag.

nodeHasChildren

Boolean. When true, content is used to render expand/collapse icons for child nodes.

The methods used to instantiate these variables are part of an internal API which are not available for public use, except when used exactly as shown in NavigationTreeInclude.jsp.

 

 

Navigation link

The following code includes the markup for both the selected and unselected nodes. Conditional coding is used so that if the node is a label (selectURL is null), then the anchor markup is not included.

<td class="<%= rowCssClass %>"  align="left">
   <% if (selectURL != null) { %>
      <a class="<%= rowCssClass %>" 
         href="<%=selectURL%>" >
   <% } %>
         <span class="wpsNavLevel<%=wpsNavLevel%>"><%= nodeTitle %></span>
   <% if (selectURL != null) { %>
      </a>
   <% } %>
    
</td>

 

Expand/collapse markup

The navigation tree provided by WebSphere Portal uses the nodeHasChildren variable to render icons for expanding and collapsing the navigation. The entire markup is in a single table cell (<td>).

• If the node has subordinate (child) nodes, then icons are displayed for expanding and collapsing the submenu. Otherwise, a spacer image (dot.gif) is rendered.

• The expand and collapse icons are rendered by the NavigationCollapsed.gif and NavigationExpanded.gif files.

The methods shown below are part of an internal API which are not available for public use, except when used exactly as described in this example.

<td class="<%= rowCssClass %>" width="14" valign="top">
<%
   if(nodeHasChildren)
   {
   // Check the node's expansion state
      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, Boolean.FALSE)%>" 
      >
      <img alt='<wps:text key="link.collapse" bundle="nls.engine"/>'  
             
           class="wpsNavExpandCollapseIcon"  
           src="<wps:urlFindInTheme  file='<%="NavigationExpanded.gif"%>'  />">
   </a>
<%
      }
      else
      {
%>
   <a 
      href="<%=wpsNavModelUtil.createStateChangeURL(wpsNavNode, 
                                 com.ibm.portal.state.StateType.EXPANSION, Boolean.TRUE)%>" 
      >
      <img alt='<wps:text key="link.expand" bundle="nls.engine"/>' 
             
           class="wpsNavExpandCollapseIcon"  
           src="<wps:urlFindInTheme file='<%="NavigationCollapsed.gif"%>' />">
   </a>
<%
      }
   }
   else
   {
%>
   <img alt=""  
        class="wpsNavExpandCollapseIcon" 
        src='<%=wpsBaseURL%>/images/dot.gif'>
<%
   }
%>
</td>

 

Indentation markup

The navigation tree provided by WebSphere Portal uses indentation as a visual indication to the user about the node's level in the portal navigation hierarchy. The scripting variable wpsNavLevel is an Integer representing the depth of the navigation level relative to the start level of the current <wps:navigation/> tag.

The method shown below is part of an internal API which is not available for public use except when used exactly as described in this example.

      <% for (int i=wpsNavLevel.intValue(); i > 1; i--) {%>
         <td width="1">&nbsp;&nbsp;&nbsp;&nbsp;</td>
      <% } %>

 

Customization tools

WebSphere Portal provides tags that support rendering tool images for editing portlets, pages, and labels. The tools are rendered when the user selects the Show Tools icon in the portal tool bar. See Providing customization tools for more information.

The customization tools should be available only for nodes in the selection path. Therefore, make sure the markup is placed within the <wps:if nodeInSelectionPath="yes"> tag. The following shows the example navigation tree with the Show Tools icon switched on.

Main     Chapter One   Chapter Two   Section One   Section Two   Chapter Three     Section One     Section Two   Chapter Four

 

 

See also

• Working with portal navigation
• Implementing a single level of navigation
• Create custom links to portlets and pages
• Providing customization tools

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.