Implement a single level of navigation

The examples in this topic show the tags used to implement a single level of navigation in the portal themes. WebSphere Portal provides two JSPs that serve as an example for single level navigation: PageBarInclude.jsp and PlaceBarInclude.jsp. Like these JSPs, any JSP you use for navigation should be included in the appropriate position in the parent JSP, typically Default.jsp.

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

  • The currently selected node, Documents, has a different background color than the other nodes for this navigation level. This gives the user a clear indication of the page that has been selected.

  • Scroll icons on the left and right of the navigation allow the user to access other nodes that are available for the navigation level. The left scroll link is disabled because there are no nodes previous to those that are displayed.

   Previous   Next     E-mail   News   Calendar   Finance   Documents   Operations reports   

The following steps show how to build a single layer of navigation using the portal JSP tags. You can add new markup or insert existing HTML markup into this structure to complete the navigation.

  1. Create the structured outline for the navigation level.

     

    The following shows the high level JSP tag structure for a navigation level.

    • The complete navigation structure is contained in the <wps:if/> tag, which ensures that the navigation is available and is rendered for one of the appropriate screens.

    • The navigation shift section contains the markup for icons used to scroll through the navigation for this level.

    • The markup for a navigation node is coded once and placed in a loop that renders links for all nodes for the given navigation level.

    • The <wps:navigation/> tag in this example specifies that all level 3 nodes for the selected parent (level 2) node are to be rendered. 
    
<%-- Start of navigation level x --%>
<wps:if navigationAvailable="yes" screen="Home,LoggedIn,LoggedOut,ErrorNotAuthorized">

<%-- Start of navigation shift --%>                      
                                                           
    <%-- code to render the scroll right icon --%>         
    <%-- code to render the scroll left icon --%>          
                                                           
  <%-- End of navigation shift --%>                        

  <wps:navigation stopLevel="3">                           
     <wps:navigationLoop>                                  
                                                           
       <%-- selected navigation node markup --%>           
          <%-- show tools markup --%>                      
       <%-- unselected navigation node markup --%>         
                                                           
     </wps:navigationLoop>                                 
  </wps:navigation>                                        

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

  2. Create the markup for a single navigation link.

     

    You should already have determined how links to navigation nodes should be rendered in the portal. Many portals use repeatable table structures to implement the navigation as tabs. You could also allow the navigation to be rendered as a drop-down box to conserve space. The entire markup must be placed inside of the navigation loop. The link markup is iterated for each node in the navigation level. Conditional logic is used to determine which node is rendered as the selected node.

     

    The following example shows the markup for a single navigation link when the node is not selected by the user.

    • The <wps:if/> tag evaluates whether the node for the current iteration of the loop is the selected node. The content of this tag is rendered if the node is not selected.

    • This example uses a table cell (<td/>), which causes the navigation links to be rendered horizontally. The wpsUnSelectedPage style class is intended for HTML elements that contain the link to the navigation node.

    • The anchor tag uses the <wps:navigationURL/> to get the URL for the node and <wps:title/> to get the locale-specific title of the node. The wpsUnSelectedPageLink style class is intended for the link to the navigation node.

      

    <wps:if nodeInSelectionPath="no">
   <td class="wpsUnSelectedPage" nowrap>
      <a class="wpsUnSelectedPageLink" href='<wps:navigationURL type="link" />' > 
         <wps:title/> 
      </a>
   </td>
</wps:if>

     

  3. Create the markup for the selected navigation node.

     

    You can provide visual aids to distinguish the selected node from the unselected nodes, indicating to users where they are in the portal structure. Like the unselected node, the entire markup must be placed inside of the navigation loop.

     

    The following example shows the markup for a single navigation link when the node is selected by the user.

    • The contents of the <wps:if/> tag are rendered if the node is selected.

    • The wpsSelectedPage and wpsSelectedPageLink style classes are used to distinguish the appearance for the selected node.

      

    <wps:if nodeInSelectionPath="yes">
   <td class="wpsSelectedPage" nowrap>
      <a class="wpsSelectedPageLink" href='<wps:navigationURL type="link" />' > 
         <wps:title/> 
      </a>
   </td>
</wps:if>

    In the preceding example, a link is created to the selected page. Clicking the link issues a request to the portal server without changing the page. You can also implement the selected node without rendering a link, for example. 

    <wps:if nodeInSelectionPath="yes">
   <td class="wpsSelectedPage" nowrap>
      <span class="wpsSelectedPageLink"> 
         <wps:title/> 
      </span>
   </td>
</wps:if>

  4. Optional. Include customization tools for the selected node.

     

    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.

     

  5. Update the links for external URL launching.

     

    Some node types include external URLs. To prevent launching a remote Web site into the portal browser window, you can add conditional coding to the link that forces a new window to open when the node is an external URL. Use the target attribute of the link to launch a new window, or you can use JavaScript as describe in this step.

     

    1. Add a JavaScript function to the page header.

      The following JavaScript should be added to the Head.jsp in the /themes/html directory. Do not use a theme-specific copy of Head.jsp (for example, /themes/html/theme_name). The tags in this file are dependent on its location in the root HTML directory. 

      
<%-- Javascript for opening external URLs in a new browser window --%>

<script language="javascript" type="text/javascript">

function NewWindow(strUrl)    
{
    window.open(strUrl, "_blank"); 
}    
</script>

    2. Determine whether the current node is external.

      The following example shows how to create a boolean variable, externalUrl, to determine whether a new browser window should be launched. This variable must be declared inside the navigation loop so that it is evaluated for each node. The wpsNavNode scripting variable represents the navigation node. If the content type of the node is an external URL, it's value is set to true.

      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. 

      
<%
// if content type is an external URL, String to open a new window
boolean externalUrl = false;
   if (com.ibm.portal.content.ContentNodeType.EXTERNALURL.equals(wpsNavNode.getContentNode().getContentNodeType()))
   {
     externalUrl = true;
   }
%>

    3. Add conditional coding to the link to invoke the JavaScript if the node is external.

      The following example shows the updated link to the navigation node.

      • If the node is an external URL, the target value will be _blank and will open a new window when clicked.
      • If the node is not an external URL, the target value will be _self and will open into the same window when clicked.
      • The style class indicates that this is for an unselected node. Portal navigation is not available for an external URL, so the selected node does not need this attribute. 
      
<td class="wpsUnSelectedPlace" nowrap height="100%">
      <a class="wpsUnSelectedPlaceLink" 
         href='<wps:navigationUrl type="link" />' 
         <% if (externalUrl){ %> onClick="NewWindow(this.href);return(false)" <% } %>   >
       <wps:title/> 
 </a>
</td>

  6. Create the markup for scrolling through the navigation.

     

    The number of nodes that can be created for a navigation level can overwhelm the space available to display all of the nodes. Portal themes can use the <wps:navigationShift/> tag to limit how many nodes are rendered for each request. Navigation shift might not be necessary if the navigation nodes are contained within a drop-down list.

     

    In the following example, a maximum of six page links can be shown in the navigation for the current level.

    • The maxPages attribute sets the maximum number of pages that can be displayed. If a user has more than six pages available, then the URL created by the nested <wps:urlParent/> tag scrolls to the next five page links, leaving one of the page links from the current set remaining.

    • The by attribute indicates the number of page links to scroll. To create a link that scrolls to the previous set of 5 page links, the by attribute must be set to "-5".

    • The scroll link is rendered as an active tab_next.gif icon when more pages are available and a disabled tab_next_dis.gif icon when there are no more pages available.

    • The pageAvailableNext attribute determines which icon to display. 
    
<wps:navigationShift by="+5" >maxPages="6">
  <wps:if pageAvailableNext="yes">
    <a href='<wps:urlParent/>'>
       <img alt="<wps:text key="link.next" bundle="nls.engine"/>" 
            src="<wps:urlFindInTheme file='<%="tab_next.gif"%>'/>" 
             align="absmiddle">
    </a>
  </wps:if>
  <wps:if pageAvailableNext="no">
    <img alt="<wps:text key="link.next" bundle="nls.engine"/>" 
         src="<wps:urlFindInTheme file='<%="tab_next_dis.gif"%>'/>" 
          align="absmiddle">
  </wps:if>
</wps:navigationShift>

     

    Notes: For the shift mechanism to function correctly, make sure the JSP tags are structured as follows.

    • The by attribute for each scroll direction must be the same absolute value. For example, if you use by="8" to shift right, then use by="-8" to shift left.
    • The maxPages attribute must be the same value for both directions.
    • At least one of the <wps:navigationShift/> tags must precede the <wps:navigationLoop/> tag.

 

See also

 

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.