<portal-navigation/> tags

 

+
Search Tips   |   Advanced Search

 

The <portal-navigation/> tags are used to implement navigation tasks such as generating URLs and traversing the portal navigation model.

The following table provides a brief description of each tag.

Do not use portal tags in portlet JSPs.. The tags mentioned below are only for use in theme and skin JSPS.

Tag Description
<portal:favoritesLoop/> Deprecated.

Replace with...

<portal-navigation:navigation/>

...in conjunction with the attribute...

scopeUniqueName
<portal-navigation:navigation/> Initialize a set of objects and make them available through scripting variables. These objects are required for the rendering process of the navigation.
<portal-navigation:navigationLoop/> Traverse through the navigation model. Nested inside of the tag...

<portal-navigation:navigation/>
<portal-navigation:navigationShift/> Create a URL for scrolling links to pages in the navigation. Used only in theme JSPs.
<portal-navigation:navigationUrl/> Provides a URL to the navigation node set in the <portal-navigation:navigationLoop/> tag. Used only in theme JSPs.
<portal-navigation:url/> Create a portal URL depending on the specified attribute.
<portal-navigation:urlGeneration/> Create a URL to pages or portlets.
<portal-navigation:urlParam/> Add parameters to the parent URL. Parent tags include...

 

Detailed descriptions of the <portal-navigation/> tags

The following section provides detailed descriptions of the <portal-navigation/> JSP tags:

<portal:favoritesLoop/>

Deprecated. Replace with...

<portal-navigation:navigation/>

...tag in conjunction with its scopeUniqueName attribute.

The following code example uses this tag to create the "Organize Favorites" functionality. To use this code, place it within the themes that you wish to have this functionality. 

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

<portal-logic:if loggedIn="yes" notScreen="SelfcareUserForm,SelfcareUserConf">

<table border="0"  cellpadding="0" >
<tr>
    <td align="<%=bidiAlignRight%>" valign="middle" dir="ltr" nowrap>
    <% boolean firstItem = true; %>        

    <table border="0" cellpadding="0"  <%= bidiDirAttr %> >
    <tr>
    <td valign="middle">

    <form tabIndex="8" 
          name="wpsFavoritesSelectionForm" method="GET" 
          style="margin-bottom: 0" 
          action='<portal-navigation:url commandParam="favoritesCommand"/>'>

    <select name="favoritesCommand" onchange="javascript: if 
  (this.options[this.selectedIndex].value.charAt(0) == '@')
 {     window.open(this.options[this.selectedIndex].value.substring(1),
  '_blank'); this.selectedIndex=0; return false;} 
 else {    this.form.submit(); return false; }">

    <option value='#' selected><wps:text key='link.favorites.myfavorites'
    bundle='nls.engine'/>

    <portal-logic:if pageBookmarkable="true">
    <option value='<portal-navigation:url command="AddBookmark"
    alias="wps.My Favorites"/>'><portal-fmt:text key='link.favorites.add'
    bundle='nls.engine'/>
    </portal-logic:if>

    <portal-navigation:urlGeneration contentNode="wps.Organize Favorites"
    portletWindowState="Normal" pacCheck="NoCheck">
    <option value='<% wpsURL.write(escapeXmlWriter); %>' >
    <portal-fmt:text key='link.favorites.orgainize' bundle='nls.engine'/>
    </portal-navigation:urlGeneration>

    <option value='#'>------------
    
    <portal:favoritesLoop>
    <% 

    // wpsFavoritesURL is null for folders in the list of favorites 
    if (wpsFavoritesURL != null)
    {

    // Check the favorite type.  If it is an external URL, add a symbol to the URL
    // so the JavaScript on the select can detect when to open a new window     // wpsFavoritesType may be null.  wpsFavoritesType=1 means external URL

    if ("EXTERNALURL".equals(wpsFavoritesType))
    wpsFavoritesURL = "@" + wpsFavoritesURL;

    //Phone number links are only supported on WML devices... and     // favorites are not markup-specific.
    // wpsFavoritesType may be null.  wpsFavoritesType=2 means Phone Number 
    if (!"2".equals(wpsFavoritesType))
    {
    %>
    <option value="<%= wpsFavoritesURL %>">
    <% for (int favSpace=1; favSpace < wpsFavoritesLevel.intValue();
    favSpace++) {%>   <% } %><%= wpsFavoritesTitle %>
    <%
    }
    }
    else     {
    %>
    <option value="#" ><% for (int favSpace=1; 
    favSpace < wpsFavoritesLevel.intValue();
    favSpace++) {%>   <% } %>--<%= wpsFavoritesTitle %>--
    <%
    }
    %>
    </portal:favoritesLoop>
    </select>
    <noscript>
    <input type="image" border="0" align="absmiddle"
    src='<portal-logic:urlFindInTheme file="go.gif"/>'/>
    <span class="wpsPlaceBarLink" > <portal-fmt:text key="go"
    bundle="nls.button"/></span>
    </noscript>
    </form>

    </td>
    </tr>
    </table>
    </td>
    </tr>
</table>
</portal-logic:if>

<portal-navigation:navigation>

Initialize a set of object and make them available through scripting variables. These objects are required for the rendering process of the navigation. The scripting variables are accessible only within the body of the tag. The settings of the startLevel and stopLevel attributes determine whether the content of the navigation tag is evaluated. The navigation tag uses an "in-order" traversal of the navigation tree to select the nodes.

Attributes:

See Working with portal navigation for examples.

<portal-navigation:navigationLoop>

Traverse through the navigation model. This tag is nested inside of...

<portal-navigation:navigation/>

...and indicates the part of the markup that will be repeated once for each navigation node.

There are no attributes for this tag.

The body of this tag is executed for each navigation node. This tag makes several scripting variables available for obtaining information for the navigation. These scripting variables are accessible only within the body of the tag.

See Implementing side navigation for more information.

<portal-navigation:navigationShift by="number" maxPages="number">

Used in the navigation to create a URL that will scroll to the next set of page links when the number of available pages exceeds maxPages. The by attribute indicates the number of page links to scroll. If this tag is not used, all page links for the current level are rendered.

See Implementing a single level of navigation for an example.

<portal-navigation:navigationUrl type="link|expand|collapse|launch" varname="node" var="variable_name"/>

Creates URLs for navigation nodes. The tag is used inside the body of the <portal-navigation:navigationLoop> tag and outputs links for the current navigation node according to the type attribute.

Attributes:

type

Use one of the following values:

  • type="link" creates a URL to change the selected node

  • type="expand" creates a URL that expands the node to reveal its child nodes. This is intended for expanding the navigation tree.

  • type="collapse" creates a URL that collapses the node to conceal its child nodes. This is intended for collapsing the navigation tree.

  • type="launch" creates a URL that either launches a page if all conditions for the page launch are fulfilled for the navigation node or if just like in the selection URL in type="link"

The global state of the portal navigation trees is collapsed by default (with some exceptions, such as the Portal Administration navigation). We can configure the default state of the portal navigation trees to expand all nodes by setting the Portal Configuration Service property navigation.expansion.defaultstate to true. For details about the portal service configuration and how to set configuration properties refer to Portal service configuration.

varname

Specifies an object of type com.ibm.portal.navigation.NavigationNode for which the URL is to be generated. The attribute is optional.

var

Name of a scripting variable that will be exposed in the body of the tag. The attribute is optional. The variable exposes an object implementing com.ibm.portal.DisposableURL that can be used to stream the URL to the output. If the content node referenced by the navigation node is an internal URL, the body is evaluated only if the target of the internal URL is accessible.

See Implementing a single level of navigation for an example. To generate the title or description of a navigation node, use the <portal-fmt:title/> or the <portal-fmt:description/> tags, respectively. This tag should be used only in theme JSPs.

<portal-navigation:url>

Create a portal URL depending on the specified attribute. Only one of the screen, command, or home attributes can be specified in a single <portal-navigation:url/> tag.

Attributes:

  • home="public|protected"

    Create a URL pointing to the public or protected (logged in) page of the portal.

  • screen="screen_name"

    Create a URL pointing to the screen name to be displayed.

  • command="LoginUser|LogoutUser|ShowTools"

    Create a URL that issues the command to the portal.

    • command="LoginUser" is used for the login panel

    • command="LogoutUser" is used for the logout button. The "userid" and "password" parameters have to be carried with a login URL.

    • command="ShowTools" toggles the value of the showTools indicator.

    See the <portal-logic:if/> tag "showtools" attribute in <portal-logic/> tags for an example.

  • commandParam="parameter_name"

    Directs the portal engine to obtain the actual command to execute from an HTTP request parameter instead of on the URL directly. The name of the parameter is the value of the commandParam attribute. This is useful in situations where different commands need to be conditionally executed yet only one URL can be specified. Such is the case when using a <form> tag with a <select>. This enables use of the HTML form without requiring JavaScript. For example: 

       <form name="someFormName" 
         method="GET" 
         style="margin-bottom: 0"
         action='<portal-navigation:url commandParam="requestParamName"/>'>

       <select name="requestParamName" 
               onchange="javascript: this.form.submit(); ">

           <portal-navigation:someLoop>
           <option value="<%= theUrl %>" >Some title goes here            </portal-navigation:someLoop>

       </select>

       <noscript>
           <input type="image" border=0 align=absmiddle src='go.gif'/>Go        </noscript>

   </form>

    The previous code example works both with and without JavaScript enabled.

  • ssl="yes|no|true|false"

    Create a secure URL (HTTPS).

Example This part of a user login form uses the <portal:url> tag to process input fields, user ID, and password. 

    <FORM method="POST"
     action='<portal-navigation:url command="LoginUser"/>'
     enctype="application/x-www-form-urlencoded"
     name="LoginPage">

<portal-navigation:urlGeneration attribute="value">

Create a URL to pages or portlets.

The tag is conditional. If the URL cannot be found, the body of the tag is not evaluated. Inside the body of the tag, the script variable...

<% wpsURL %>

...can be used to write the URL directly to the output stream. For example... 

   
    <a class="wpsToolBarLink" 
       ref='<% wpsURL.write(out); %>'>My page</a>

Attributes:

  • accessControlCheck="permission_constant"

    Permissions to be checked. Constants include...

    • CreatePage
    • EditLayout
    • DeletePage
    • AssignRoles
    • NoCheck
    • EditApplicationProperties
    • EditApplicationLayout
    • AssignApplicationMember
    • ManageApplicationRoles
    • SaveAsTemplate

    If the user does not have the given permission, the body of the tag is not executed. If the user has the necessary permissions, the current page ID is appended to the URL. If the parameter is set to 'NoCheck', the current page ID is appended without checking the access control permissions. This is necessary for the target page or portlet to create a back button.

  • actionName="name"

    Name of an action that would be invoked by the URL to an IBM portlet. The following example generates a URL that calls the myAction action of the portlet which is contained by my.LayoutNode on my.ContentNode. 

        
    <portal-navigation:urlGeneration actionName="myAction" contentNode="my.ContentNode" 
      layoutNode="my.LayoutNode">
   <a href="<%wpsURL.write(out)%>">Link to portlet with myAction</a>
    </portal-navigation:urlGeneration>
    The following is the code from the portlet's actionPerformed() that would handle myAction. 

     PortletURI actionURL = portletResponse.createURI();
 actionURL.addAction("myAction");

  • allowRelativeURL="true|false"

    Whether a fully-qualified or relative URL is generated. The default is set by the property...

    com.ibm.portal.state.accessors.url.URLContext.enableRelative

    ...in...

    StateManagerService

  • contentNode="id|name"

    ID or unique name of the page. The name or ID of the content node is also used to specify the page where the portlet can be found.

  • keepNavigationalState="true|false"

    If set to false, the current navigational state (including all portlet modes, states, and render parameters) is not included in the URL and the portal is reset to its default state. If set to true, which is the default, navigational state is included.

  • layoutNode="id|name|wp.currentSelectedPortlet "

    ID or unique name of the control that holds the portlet. Must be used in combination with contentNode to identify the page where the portlet is located.

    The value wp.currentSelectedPortlet can be used inside a control when generating a URL to the portlet within that control.

  • newWindow=""true|false""

    Create a session partition. For portlet URLs, this should be used if you want to display the portlet either in a new window or in an iFrame. The default value is false. The portlet window state for the addressed portlet in the new window is set to maximized. The portlet mode is set to the value of the current parent window. In the control.jsp of Skins that use iFrames, the <portal:if/> tag can be used to distinguish between rendering in the main window or in an iFrame or detached window.

  • portletMode="view|help|edit|configure"

    For URLs to a portlet indicated by layoutNode, this attribute sets the portlet mode. This parameter is ignored if layoutNode is not set.

  • portletWindowState="maximized|minimized|solo|normal"

    in the case of a portlet, indicates the state of the portlet window when it is displayed. If portlet state is not specified, the page is shown with the previous state of the portlet. This parameter is ignored if layoutNode is not set.

    Use caution when using this tag to address portlets in solo state. The portlet must be capable of exiting solo state using the createReturnURI() method. If a portlet without this method is placed in solo state, then users are forced to log out or close their browser windows in order to return to the portal.

  • themeTemplate="template_name"

    Specifies the ThemeTemplate which will be taken for rendering the requested page.

  • normalize="true|false"

    This parameter indicates that the URL to be generated should be normalized. If additional parameters are set the normalization will be executed first and afterwards the other state modifications will be accomplished. Setting the "normalize" parameter to true will normalize the URL with the same XSL file used to normalize URLs for search engines. The normalized representation of the URL can also be used to bookmark a page. The following example shows how to use the tag with this attribute: 

    <portal-navigation:urlGeneration normalize="true" >
  <a href="<% wpsURL.write(out); %>">
    This is the normalized URL of the current 
    selected page.
  </a>    
</portal-navigation:urlGeneration>

    If additional parameters are set for the <portal-navigation:urlGeneration> tag the XSL transformation will be executed first and all other state modifications will be accomplished afterwards.

See Create custom links to portlets and pages for examples.

<portal-navigation:urlParam name="parameter_name" value="parameter_value">

Used to add parameters to the parent URL. Parent tags include...

Parameters added to the <urlGeneration/> tag occur as unscoped query parameters unless the attributes specify otherwise.

Parameter handling depends on the target of the URL. If the URL points to a page, the parameters are visible to all IBM portlets on that page. Parameters are not visible to standard portlets if the URL does not point specifically to that portlet.

Attributes:

  • name

    Required. Name of the parameter.

  • value

    Required. Value of the parameter.

  • type

    Optional. Indicates one of the following types...

    render Render parameter for the portlet.
    action Action parameter for the portlet.
    query Name value pair is added to the URL as a query parameter. Default if type not specified.

 

Related information