"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> Tags used by the portal JSPs

 

Tags used by the portal JSPs

 

+
Search Tips   |   Advanced Search

 

Overview


  1. Overview
  2. Summary of the portal JSP tags
  3. Detailed descriptions of the portal JSP tags

 

Overview

Use the tags in the portal tag library, portal.tld,...

$ ls $WP_ROOT/shared/app/WEB-INF/tld
DocEditor.tld              c-rt.tld     engine.tld       fmt.tld              personTag.tld        
WCLTagLib50.tld            c.tld        engine_v2.tld    ibm-portlet-ext.tld  portal-internal.tld
WpsWCLExtensionTagLib.tld  c2a.tld      epi-portlet.tld  menu.tld             portal-wml.tld
admin.tld                  content.tld  fmt-rt.tld       people.tld           portal.tld
portlet.tld                sql-rt.tld   x-rt.tld         sql.tld              x.tld
std-portlet.tld            transcoding.tld  

...to modify the appearance and layout of the portal page. Do not use portal tags in portlet JSPs.

To use the portal tag library, include the following taglib declaration in the parent JSP....

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

 

Notes

The tags in the portal-internal.tld tag library are not intended for customization, but for use only by internal portal code.

The tags in the engine.tld tag library are not intended for customization, but only to support backward compatibility and migration. This tag library will not be available in subsequent releases of WebSphere Portal.

References to nls.engine tie back to the ../nls directory. For example, on an iSeries box, edit...

/qibm/userdata/WebAS5/Base/WAS5Portal/PortalServer5/shared/app/nls/engine.properties

 

Summary of the portal JSP tags

Tag Description
<wps:answer/> Return the answer text for a given key in the specified language. Used only within a <wps:portletRender/> or <wps:pageRender/> tag.
<wps:bidi/> Support the display of bidirectional languages.
<wps:closePage/> Provide a URL that closes a dynamically created task page. Used only within a <wps:navigationLoop/>
<wps:constants/> Make the <%= wpsBaseURL %> and <%= wpsDocURL %> constants available to the page.
<wps:description/> Description of an object that implements the Localized interface. Used only in theme JSPs.
<wps:favoritesLoop/> Make several scripting variables available related to bookmarking portal URLs (favorites).
<wps:find/> Used to access the portal-wide find URL that is specified in Portal Settings. Used only in theme JSPs.
<wps:if/> Through the attributes of this tag, several conditions can be checked. If the condition is true, the content of the tag is written to the page.
<wps:layoutNodeLoop/> Generates the markup for the area of the portal page that includes the portlets. Used only in skin JSPs.
<wps:layoutNodeProperty/> Displays the value of a property of a given layout node or exposes the value of the property in a scripting variable.
<wps:layoutNodeRender/> Renders an element of the layout model. Used only within a <wps:layoutnodeLoop/>.
<wps:navigation/> Make the wpsNavModel scripting variable available, which is used in the body of the tag to render navigation nodes. Used only in theme JSPs.
<wps:navigationLoop/> Cycles through navigation nodes (wpsNavNode) and children. Used only in theme JSPs.
<wps:navigationShift/> Used to create a URL for scrolling links to pages in the navigation. Used only in theme JSPs.
<wps:navigationUrl/> Provide a URL to the navigation node set in the <wps:navigationLoop/> tag. Used only in theme JSPs.
<wps:pageRender/> Used in the Home screen to render the content of the selected page. Do not confuse this with the <wps:pageRender/> tag deprecated in V4.2.
<wps:pendingTasks/> Through the use of scripting variables, notifies the user whenever a new, unclaimed task has been assigned. Used only within theme JSPs.
<wps:portletBack/> Render the icon in the portlet title bar to allow the user to return to a previous mode. Used only in skin JSPs.
<wps:portletConfigure/> Render the icon in the portlet title bar to allow the administrator to configure the portlet. Used only in skin JSPs.
<wps:portletDelete/> Render the icon in the portlet title bar to remove the portlet from the page. Used only in skin JSPs.
<wps:portletEdit/> Render the icon in the portlet title bar to allow the user to edit the portlet. Used only in skin JSPs.
<wps:portletHelp/> Render the icon in the portlet title bar to display portlet help. Used only in skin JSPs.
<wps:portletMaximize/> Render the icon in the portlet title bar to allow the user to maximize the portlet. Used only in skin JSPs.
<wps:portletMinimize/> Render the icon in the portlet title bar to allow the user to minimize the portlet. Used only in skin JSPs.
<wps:portletMoveDown/> Render the icon in the portlet title bar that allows the user to move the portlet down on the page. Used only in skin JSPs.
<wps:portletMoveLeft/> Render the icon in the portlet title bar that allows the user to move the portlet to the left on the page. Used only in skin JSPs.
<wps:portletMoveRight/> Render the icon in the portlet title bar that allows the user to move the portlet to the right on the page. Used only in skin JSPs.
<wps:portletMoveUp/> Render the icon in the portlet title bar that allows the user to move the portlet up on the page. Used only in skin JSPs.
<wps:portletRender/> Renders portlet content into the layout of the page that is currently being generated. Used only in skin JSPs.
<wps:portletRestore/> Render the icon in the title bar to allow the user to restore the portlet to its original state. Used only in skin JSPs.
<wps:portletTitle/> Write the title for a portlet. Used only in skin JSPs.
<wps:problem/> Return the problem text for a given key in the specified language. Used only within a <wps:portletRender/> or <wps:pageRender/> tag.
<wps:screenRender/> Start the rendering of the screen. Used only in theme JSPs.
<wps:stateBase/> Stores a base URL which can be used instead of full, newly-coded URLs on each occurrence of a URL in the markup. This tag should occur only in the header section of the markup, which is provided by theme JSPs.
<wps:text/> Return the text for a given key in the specified language. This is getting replaced by the <i18n:bundle/> and <i18n:message/> tags of the I18N tag library. See Using JSTL tags in the portal JSPs for more information.
<wps:textParam/> If the text that is retrieved contains placeholders in the form of "{0}", "{1}", "{2}", ..., these can be set using this tag. Used only in the body of the <wps:text/> tag.
<wps:title/> Localized title of the navigation node set in the <wps:navigationLoop/> tag. Used only in theme JSPs.
<wps:unless/> This tag operates in contrast to the <wps:if> tag.
<wps:url/> Create a portal URL depending on the specified attribute.
<wps:urlFind/> Generates a URL pointing to a file.
<wps:urlFindInSkin/> Similar to <wps:urlFind>, this tag generates a URL pointing to a file in the /skins directory.
<wps:urlFindInTheme/> Similar to <wps:urlFind>, this tag generates a URL pointing to a file in the /themes directory.
<wps:urlGeneration/> Create a URL to pages or portlets.
<wps:urlParam/> Add parameters to the parent URL. Parent tags include the <wps:url/> and <wps:urlGeneration/>.
<wps:urlParent/> Create a URL that supports one of the following surrounding tags.
<wps:user/> If the user is logged in, this tag returns one of the specified values of attribute.

 

Detailed descriptions of the portal JSP tags

The following tags are used by the portal JSPs.

 

<wps:answer bundle="bundle">

Return the answer text for a given key in the specified language. The following keys can be looked up in the resource bundle.

  • content.not.available.answer

  • login.invalid.answer

  • password.invalid.answer

  • userid.invalid.answer

  • portlet.not.active.answer

  • portlet.not.authorized.answer

  • portlet.not.available.answer

  • portlet.title.not.available.answer

Each key corresponds to a problem key (without the .answer suffix). See the <wps:problem> tag for a complete description of each problem and a complete example.

 

<wps:bidi dir="rtl|ltr" attribute="portlet" locale="locale">

Support the display of bidirectional languages. Bidirectional languages are those that are typically read from right to left except when left-to-right text strings are displayed (for example, URLs, code samples, or directory and file names).

Attributes

  • dir

    Indicates the normal direction of text in the language. This attribute is required.

    • For dir="rtl", the tag content is written only if the client's locale belongs to a bidirectional language. This is the default setting if dir is not specified.

    • For dir="ltr", the tag content is written only if the client's locale does not belong to a bidirectional language.

  • attribute="portlet"

    Indicates that the text is for the title of a portlet. This attribute is optional.

  • locale

    The tag content is written only if the language belongs to the bidirectional languages that are defined in LocalizerService.properties . If attribute is specified, locale is ignored.

WebSphere Portal JSPs use this tag in a BidiInclude.jsp that creates the following scripting variables which, in many cases, are easier to use and recommended over the <wps:bidi/> tag.

<%=bidiAlignRight%>

resolves as the value left for BIDI languages, right for all other languages. This is primarily intended for text alignment, such as in a table cell.

<%=bidiAlignLeft%>

resolves as the value right for BIDI languages, left for all other languages. This is primarily intended for text alignment, such as in a table cell.

<%=bidiImageRight%>

resolves as the value Left for BIDI languages, Right for all other languages. This is primarily intended to append the value to the filename for an image. For example, the theme directory provide two image files that can be used for the top corners of a portlet window, Album_Border_TopLeft.gif and Album_Border_TopRight.gif.

<%=bidiImageLeft%>

resolves as the value Right for BIDI languages, Left for all other languages. This is primarily intended to append the value to the filename for an image.For example, the theme directory provide two image files that can be used for the top corners of a portlet window, Album_Border_TopLeft.gif and Album_Border_TopRight.gif.

<%=bidiImageRTL%>

resolves to the value _rtl for BIDI languages, null for all other languages. This is primarily intended for graphic images. For example, the skin previews provide two image files to preview the skin, preview.gif and preview_rtl.gif.

The following example shows how a directional image is invoked. The <%=bidiImageRTL%> scripting variable is used to invoke the appropriate icon, for example, tab_next_rtl.gif, when the locale belongs to a bidirectional language.


  <img alt="<wps:text key="link.next" bundle="nls.engine"/>" 
   src="<wps:urlFindInTheme file='<%="tab_next"+bidiImageRTL+".gif"%>'/>" 
    align="absmiddle">

 

<wps:closePage/>

Provide a URL that closes a dynamically created task page. Used only within a <wps:navigationLoop/>. See Customizing the theme for process integration for more information.

 

<wps:constants>

Make the following constants available to the page:

  • <%= wpsBaseURL %>

    Fully qualified base URL of the portal site as specified during installation, for example...

    http://<hostname.yourco.com>:<port_number>/wps

  • <%= wpsDocURL %>

    URL to the product documentation located in the WebSphere Portal Web application directory, including the Javadoc, and portal help. The URL returned includes the locale of the client, for example...

    http://myserver.mydomain.com/wps/doc/locale/

    For example, the following code would generate a URL to the Javadoc:

     <%= wpsDocURL %>/Javadoc/WPS/index.html   
     

 

<wps:description locale="locale" varname="scripting_variable" />

Localized description of the navigation node set in the <wps:navigationLoop/> tag.

Attributes

locale

Optional. Overrides the current language setting.

varname

Optional. Specifies the name of the scripting variable holding the localized object. The <wps:navigation/> tag sets this object to <%=wpsNavNode%>.

<wps:navigationLoop>
  <!-- write the description of the node in the current locale -->
 <wps:description varname="<%=wpsNavNode%>"/>
  <!-- write the description of the node in chinese -->
 <wps:description varname="<%=wpsNavNode%>" locale="zh"/>
</wps:navigationLoop>

 

<wps:favoritesLoop/>

Make the following scripting variables available inside the body of the tag. The body of this tag is executed for each favorite.

  • <% wpsFavoritesURL %> - the URL to access the favorite

  • <% wpsFavoritesTitle %> - the title of the favorite

  • <% wpsFavoritesType %> - retrieves a String that indicates the type of favorite:

    • composition - a bookmark for a URL to a page

    • externalurl - a bookmark for the URL to an external location

    • internalurl - a bookmark for the URL to an internal location

    • label - a bookmark for a URL to a label

  • <% wpsFavoritesLevel %> - indicates the level in the favorites tree hierarchy. For example, a level 2 favorite is a bookmark that has been placed in a folder of the favorites root.

 

<wps:find>

Used to access the portal-wide find URL that is specified in Portal Settings. The tag is conditional. If no URL is set, the body of the tag is not evaluated. A scripting variable called <% wpsFindURL %> is available inside the body of the tag for accessing the URL. Used only in theme JSPs.

 

<wps:if attribute="value">

Through the attributes of this tag, several conditions can be checked. If the condition is true, the content of the tag is written to the page. Otherwise the content is skipped. More than one condition can be evaluated. For example, the user must be logged in and the Home screen must be active for the content of the following tag to be rendered:
 <wps:if loggedIn="yes" screen="Home">

  <!--  content area -->

 </wps:if>
 

Attributes of the <wps:if/> tag

  • capableOf="capability"

    indicates whether the client supports the specified capability. capability can be one of the following values:
    • HTML_2_0

    • HTML_3_0
    • HTML_3_2
    • HTML_4_0
    • HTML_CSS
    • HTML_FRAME

    • HTML_JAVA
    • HTML_JAVASCRIPT
    • HTML_NESTED_TABLE
    • HTML_TABLE
    • WML_1_0

    • WML_1_2
    • WML_TABLE

     

  • locale="locale"

    Indicates whether the locale of the client is that of the specified locale (or subtype of the specified locale). You can specify a comma-separated list, such as en, en_US .

     

  • loggedIn="yes|no"

    Indicates whether the user is logged in. For example, the following code will display a login link if the user is not logged in:

    
     <%-- login button --%>
     <wps:if loggedIn="no" notScreen="Login">
     <td class="wpsToolBar" valign="middle" nowrap>
      <a class="wpsToolBarLink" 
       href='<wps:url home="public" screen="Login" ssl="false"/>'>
        <wps:text key="link.login" bundle="nls.engine"/>
      </a>
     </td>
     </wps:if>
    
     

     

  • navigationAvailable="yes|no"

    Indicates if a navigation is available.

     

  • newWindow="yes|no"

    Indicates if the portlet is rendered in a separate browser window from the portal (HTML only).

     

  • nodeInSelectionPath="yes|no"

    Checks whether a page is selected. This means that the page is in the selected path by the user of which the content is shown.

     

  • notLocale="locale"

    Indicates if the locale is not of the specified value. This attribute operates in contrast to locale.

     

  • notScreen="screen_name"

    Indicates if the current screen is not of the specified value. This attribute operates in contrast to screen.

     

  • notSelection

    specifies the unique name or object ID of that should not be the currently selected page. For example:

     <wps:if notSelection="wps.My Portal">
     You are not on My Portal
     </wps:if>
     

     

  • pageAvailableNext="yes|no"

    Checks if a subsequent set of pages are available to be accessed from the navigation. See Create the markup for scrolling through the navigation for an example.

     

  • pageAvailablePrevious="yes|no"

    Checks if a previous set of pages are available to be access from the navigation. For example, this tag could be used in combination with a <wps:navigationShift> to render a scroll icon when the number of user-defined pages exceeds the number of displayed page tabs. This condition behaves contrary to the pageAvailableNext attribute. See Create the markup for scrolling through the navigation for an example.

     

  • pageCompletelyActive="yes|no"

    Indicates whether the page and its parents are active. The following example displays a message if the page is not active.

    
     <wps:if pageCompletelyActive="no">
      <p align="center" class="wpsFieldErrorText"><b><br>
       &gt;&gt;&gt;
         <wps:text key="info.pagenotcompletelyactive" bundle="nls.engine"/>
       &lt;&lt;&lt;
      <br></b></p>
     </wps:if>
     

     

  • pageBookmarkable="true|false"

    Renders its contents if the page can be bookmarked. A page can be set to bookmarkable using Manage pages. The following example provides an "Add to favorites" option in a select list to allow users to bookmark the current page, if the current page can be bookmarked.

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

     

  • portletMaximized="yes|no"

    Renders its contents if the portlet is maximized.

     

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

    Checks if the portlet supports the requested mode. This tag is most useful in a customized skin. The skin JSPs are located in was_root/installedApps/hostname/wps.ear/wps.war/skins/markup/.

     

  • portletState="portlet_state"

    Checks if the portlet is in the indicated state. Portlet states are normal, maximized, minimized, and solo. For example, in Control.jsp, the following code sets the tableHeight variable to 100%.

    
     <wps:if portletState="Normal,Maximized">
     <% tableHeight = "height=\"100%\""; %>
     </wps:if>
     

     

  • portletSolo="yes|no"

    Checks whether the portal is currently displaying a portlet in solo state. In the following example from Default.jsp, the toolbar is always displayed, but the placebar and pagebar are hidden when the current portlet is displayed in solo state.


     <td  height="1" valign="top">      
      <%@ include file="./ToolBarInclude.jsp" %> //
         
      <%-- Don't show navigation in solo mode --%>
      <wps:if portletSolo="no">
       <%@ include file="./PlaceBarInclude.jsp" %>          
       <%@ include file="./PageBarInclude.jsp" %>
      </wps:if>
         
     </td>
     


    See Solo state for more information.

     

  • problem="problem"

    Renders its contents if one of the following problems has occurred.

    • content.not.available

    • login.invalid

    • password.invalid

    • portlet.not.active

    • portlet.not.authorized

    • portlet.not.available

    • portlet.title.not.available

    • userid.invalid

    See <wps:problem/> for a complete description of each problem.

     

  • resumeLevel="0|1|2"

    Used in the Login.jsp screen to write the content of the tag if the value of this attribute is equal to the setting of the persistent.session.level key in ConfigService.Properties . See Persistent session state for more information about this setting.

     

  • resumeOption="0|1"

    Used in the Login.jsp screen to write the content of the tag if the value of this attribute is equal to the setting of the persistent.session.option key in ConfigService.Properties . See Persistent session state for more information about this setting.

     

  • screen="screen_name"

    Checks the value of the current screen name. Use a comma to separate multiple screen names. In the following example, the content of the tag is displayed only when the selected screen is Home, LoggedIn, or LoggedOut.

    
     <wps:if navigationAvailable="yes" screen="Home,LoggedIn,LoggedOut">  
    
     ....
    
     </wps:if>
     
     

     

  • selection

    specifies the unique name or object ID of the currently selected page. For example:

    
     <wps:if selection="wps.My Portal">
     You are on My Portal
     </wps:if>
    
     

     

  • showTools="yes|no"

    Indicates whether additional controls for the portlet title bar and page tabs should be displayed. In the following example from ToolBarInclude.jsp, the show_tools_off.gif icon is displayed for the condition when showTools="no".

    
     <wps:if loggedIn="yes">
     <wps:if showTools="no">
      <% if (firstButton) { firstButton = false; } else { %> | <% } %>
      <a class="wpsToolBarLink" href='<wps:url command="ShowTools"/>'> 
       <img  align="absmiddle" width="16"  
         src='<wps:urlFindInTheme file="show_tools_off.gif"/>' 
         alt='<wps:text key="link.show.tools" bundle="nls.engine"/>' 
         title='<wps:text key="link.show.tools" bundle="nls.engine"/>'
       </a>
     </wps:if>
     <wps:if showTools="yes">
      <% if (firstButton) { firstButton = false; } else { %> | <% } %>
      <a class="wpsToolBarLink" href='<wps:url command="ShowTools"/>'> 
       <img  align="absmiddle" width="16"  
        src='<wps:urlFindInTheme file="show_tools_on.gif"/>' 
        alt='<wps:text key="link.hide.tools" bundle="nls.engine"/>' 
        title='<wps:text key="link.hide.tools" bundle="nls.engine"/>'</a>
     </wps:if>
     </wps:if>
     

    For either condition, the <wps:url command="ShowTools"/> command is used to change the value of showTools, allowing the icon on the portal page to be used as a toggle. This condition is also checked in ShowTools.jsp to determine whether to render the move and delete portlet icons in the portlet title bar. See Show tools for more information about how this function is used.

     

 

<wps:layoutNodeLoop var="var_name">

Generates the markup for the area of the portal page that includes the portlets. The layout nodes are used for laying out containers (rows, columns) or controls (portlets). The tag iterates children of a layout node. By specifying the var attribute, the currently used layout node can be made available for use in other tags that expect scripting variable names.
<%@ taglib uri="/WEB-INF/tld/engine_v2.tld" prefix="wps" %>

<table cellpadding=10 align="center">
<tr height="100%">
  <wps:layoutNodeLoop var="node">
  <td valign="top" width=<wps:layoutNodeProperty varname="node" propertyname="WIDTH"/>>
 <wps:layoutNodeRender/>
  </td>
  </wps:layoutNodeLoop>
</tr>
</table>

 

<wps:layoutNodeProperty/>

Displays the value of a property of a given layout node or exposes the value of the property in a scripting variable. Mandatory attributes are:

  • varname - the name of the variable holding the layout node

  • propertyName - the name of the property to retrieve (for example, "WIDTH" or "ORIENTATION")

The optional attribute var can be used to expose the value of the property in a scripting variable of the given name instead of writing it to the output directly.

Example:

<wps:layoutNodeLoop var="wpsLayoutNode">
  <wps:layoutNodeProperty varname="<%=wpsLayoutNode%>" propertyname="WIDTH"/>
  <!-- write the width property !-->
  <wps:layoutNodeProperty varname="<%=wpsLayoutNode%>" propertyname="WIDTH" var="width" />
  <!-- expose width variable !-->
 ... <img width="<%=width>" src="test.gif"> ...
  </wps:layoutNodeProperty>
</wps:layoutNodeLoop>

<wps:layoutNodeRender>

Renders an element of the layout model. This might be a container representing a row, column, or a control. This tag can only be used within a <wps:layoutNodeLoop> tag.

 

<wps:navigation>

Renders the portal navigation. 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. 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

  • startLevel

    (optional) The level on which this navigation is to begin showing information. If no start level is given, this tag will start at the navigation node after the levels that where shown by other JSPs . Otherwise, the default is level 1.

  • stopLevel

    (optional) The level on which this navigation is to stop showing information. Default is to render all levels.

  • computeNumLevelsToDisplay

    (optional) Compute the number of levels that will actually be shown by this navigation. When this attribute is set to "true", a scripting variable is made available inside the body of the navigation tag named wpsNavNumLevelsToDisplay of Java type java.lang.Integer.

See Working with portal navigation for examples.

 

<wps:navigationLoop>

This tag can only be used within the body of a <wps:navigation> tag. This tag 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 a navigation tree for more information.

 

<wps: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 Create the markup for scrolling through the navigation for an example.

 

<wps:navigationUrl type="link|expand|collapse" varname="node_name" />

Creates URLs for navigation nodes. The tag is used inside the body of the <wps: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.

varname

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

See Implementing a single level of navigation for an example. To generate the title or description of a navigation node, use the <wps:title/> or the <wps:description/> tags, respectively. Used only in theme JSPs.

 

<wps:pageRender/>

Used in the Home screen to render the content of the selected page. Do not confuse this with the <wps:pageRender/> tag deprecated in V4.2. This tag renders the portal page without the navigation. When this tag is called, all pages that are available for the user are determined.

 

<wps:pendingTasks/>

Through the use of scripting variables, notifies the user whenever a new, unclaimed task has been assigned. Used only within theme JSPs. See Customizing the theme for process integration for more information.

 

<wps:portletBack>

Used in the control to render the icon in the portlet title bar to allow the user to return to a previous mode. The content of this tag should include a link (HREF value should be <%=wpsPortletBackURL%>) and an icon image. The link for taking the portlet back is generated depending on the portlet's current window state. Used only in skin JSPs.
 <wps:portletBack>
  <td class="wpsPortletTitle">
   <a href='<%=wpsPortletBackURL%>'>
    <img  align="absmiddle" width="12" 
     src="<wps:urlFindInTheme file='<%= "title_back" + bidiImageRTL + ".gif" %>'/>"
     alt='<wps:text key="back" bundle="nls.titlebar"/>'
     title='<wps:text key="back" bundle="nls.titlebar"/>'></a></td>
 </wps:portletBack>
 

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletConfigure newWindow="true|false|yes|no">

Used in the control to render the icon in the portlet title bar to allow the administrator to configure the portlet. The content of this tag should include a link (HREF value should be <%=wpsPortletConfigureURL%>) and an icon image. The newWindow attribute is not supported for this mode. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletDelete/>

Used in ShowTools.jsp to render the link in the portlet title bar to remove the portlet from the page. Before showing the delete portlet icon, the tag checks if the portlet can be deleted by the user. The content of this tag includes a link (HREF value should be rendered as <%=wpsPortletDeleteURL%>) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletEdit newWindow="true|false|yes|no">

Used in the control to render the icon in the portlet title bar to allow the user to edit the portlet. The content of this tag includes a link (rendered as <%=wpsPortletEditURL%> or <wps:urlParent>) and an icon image. The newWindow attribute is not supported for this mode. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletHelp newWindow="true|false|yes|no">

Used in the control to render the icon in the portlet title bar to display portlet help. The content of this tag includes a link (rendered as <%=wpsPortletHelpURL%> or <wps:urlParent>) and an icon image. The newWindow attribute indicates that, for HTML, the portlet help should be rendered in a new browser window. The default is "no" or "false". Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletMaximize>

Used in the control to render the icon in the portlet title bar to allow the user to maximize the portlet. Before showing the maximize button, the tag checks if the portlet supports the maximize state or if the portlet is already in that state. The content of this tag includes a link (rendered as <%=wpsPortletMaximizeURL%> or <wps:urlParent>) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletMinimize>

Used in the control to render the icon in the portlet title bar to allow the user to minimize the portlet. Before showing the minimize button, the tag checks if the portlet supports the minimize state or if the portlet is already in that state. The content of this tag includes a link (rendered as <%=wpsPortletMinimizeURL%> or <wps:urlParent">) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletMoveDown/>

Used in ShowTools.jsp to render the icon in the portlet title bar that allows the user to move the portlet down on the page. Before showing the move down button, the tag checks if the portlet can be moved down. The content of this tag includes a link (rendered as <wps:urlParent/>) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletMoveLeft/>

Used in ShowTools.jsp to render the icon in the portlet title bar that allows the user to move the portlet to the left on the page. Before showing the move left button, the tag checks if the portlet can be moved left. The content of this tag includes a link (rendered as <wps:urlParent/>) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletMoveRight/>

Used in ShowTools.jsp to render the icon in the portlet title bar that allows the user to move the portlet to the right on the page. Before showing the move right button, the tag checks if the portlet can be moved right. The content of this tag includes a link (rendered as <wps:urlParent/>) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletMoveUp/>

Used in ShowTools.jsp to render the icon in the portlet title bar that allows the user to move the portlet up on the page. Before showing the move up button, the tag checks if the portlet can be moved up. The content of this tag includes a link (rendered as <wps:urlParent/>) and an icon image. Used only in skin JSPs.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletRender>

Renders portlet content into the layout of the page that is currently being generated. This tag can be used only within the control in the skin JSPs.

If a portlet is not active or deactivated, the body of the tag is executed and a corresponding message can be shown with the <wps:problem/> tag, or other error handling can be implemented. The body of the tag could hold further JSP code.

See the <wps:problem> tag or <wps:if portletstate> for an example of how this tag is used in Control.jsp .

 

<wps:portletRestore>

Used in the control to render the icon in the portlet title bar to allow the user to restore the portlet to its original state. The content of this tag includes a link (rendered as <%=wpsPortletRestoreURL%> or <wps:urlParent>) and an icon image.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:portletTitle id="identifier">

Write the title for a portlet. If the portlet is not available or disabled, a special title is written that indicates that the origin title is not available. The content of the tag is evaluated only if problems occur during the processing and can be used for error processing. When id is specified, the tag initializes a scripting variable with the value that is normally written out and nothing is written to the output stream. The value of the id attribute is the name of the scripting variable. Used only in skin JSPs.

For JSR 168 compliant portlets, only static titles are displayed. Titles that are dynamically set using the RenderResponse.setTitle() method are ignored.

In this example in Control.jsp, the title is rendered in a table cell. Alignment is determined by the <%= bidiAlignLeft %> variable, which is set in the file BidiInclude.jsp.

 
 <td class="wpsPortletTitle"  nowrap align="<%= bidiAlignLeft %>" valign="middle">
 <wps:portletTitle>
   <wps:problem bundle="nls.problem"/>
  </wps:portletTitle> 
  <img alt=""  width="1" 
   src='<wps:urlFindInTheme file="title_minheight.gif"/>'>
 </td>
 

 

<wps:problem bundle="bundle">

Return the problem text for a given key in the specified language. The following keys can be looked up in the resource bundle.

  • content.not.available - Occurs if there is no page content that can be displayed. Used in the <wps:pageRender/> tag.

  • login.invalid - Occurs when the user ID, password, or both are not valid. This is used in the Login screen.

  • password.invalid - Occurs when the password field is empty during login. This is used in the Login screen.

  • portlet.not.active - Occurs when a portlet is not active. Used in the <wps:portletRender/> tag.

  • portlet.not.authorized - Occurs when a user does not have appropriate permissions on a portlet. Used in the <wps:portletRender/> tag.

  • portlet.not.available - Occurs when an error occurs that prevents a portlet from rendering. Used in the <wps:portletRender/> tag.

  • portlet.title.not.available - Occurs when a portlet title is not available. Used in the <wps:portletTitle/> tag.

  • userid.invalid - Occurs when the user ID field is empty during login. This is used in the Login screen.

There is a corresponding answer key for each problem (see the <wps:answer/> tag).

The resource bundle must be located in the wp_root/shared/app directory. The following sample retrieves the problem text from /nls/problem_locale.properties. The text is displayed only when an error is encountered rendering the page.

Example

 
 <wps:pageRender>
  <p align="center">
  <strong><wps:problem bundle="nls.problem"/></strong>
  <br>
  <wps:answer bundle="nls.problem"/>
  </p>
 </wps:pageRender>

 

 

<wps:screenRender/>

Renders the current screen. Types of screens include Home (default), Login, and Error. This tag can only be used once in the portal. Used only in theme JSPs.

Example

This part of the Default.jsp puts the screen in a row underneath the portal toolbar, place bar, and page bar.


 <table  cellpadding=10  height="100%">
 <tr>
   <td  height="1" valign="top">
     <%@ include file="./ToolBarInclude.jsp" %>
     <%@ include file="./PlaceBarInclude.jsp" %>
     <%@ include file="./PageBarInclude.jsp" %>
   </td>
 </tr>
 <tr>
   <td  height="100%" valign="top">
    <wps:screenRender/>
   </td>
 </tr>
 </table>
 

 

<wps:stateBase/>

Stores a base URL which can be used instead of full, newly-coded URLs on each occurrence of a URL in the markup. This enables shorter URLs and can improve the page serving performance. This tag should occur only in the header section of the markup - it is not allowed to occur outside of the header section. Theme JSPs are responsible for the header section, using Head.jsp by default.

See Generating relative URLs for more information.

 

<wps:text key="key" bundle="bundle">

Return the text for a given key in the specified language. The key indicates a parameter in a resource bundle or properties file, indicated by bundle. Both attributes are required. See the description of <wps:textParam> for an example and further description of the attributes of <wps:text/>.

Where possible, the <i18n:bundle/> and <i18n:message/> tags of the I18N tag library should be used instead of <wps:text/>. See Using JSTL tags in the portal JSPs for more information.

 

<wps:textParam>

If the text that is retrieved contains placeholders in the form of "{0}", "{1}", "{2}", ..., these can be set using this tag. Used only in the body of the <wps:text/> tag. The text to be substituted for the placeholders needs to be entered as content for this tag. It can even be an expression.

Examples

The welcome parameter in a resource bundle is set as follows:

  welcome = Welcome {0}!
 

In the following example, the value of the <wps:textParam> tag is written in place of the {0}.

 <wps:text key="welcome" bundle="nls.engine">
 <wps:textParam>World</wps:textParam>
 </wps:text>
 

 

<wps:title locale="locale" />

Localized title of the navigation node set in the <wps:navigationLoop/> tag.

Attributes

locale

Optional. Overrides the current language setting.

varname

Optional. Specifies the name of the scripting variable holding the localized object. The <wps:navigation/> tag sets this object to <%=wpsNavNode%>.

See Implementing a single level of navigation tabs for an example.

 

<wps:unless>

This tag operates in contrast to the <wps:if> tag. Through the attributes of this tag, several conditions can be checked. If the condition is true, the content of the tag is not written to the page. Otherwise, the content is written. More than one condition can be evaluated. The following attributes can be evaluated. For more information, see the corresponding description for each attribute under the <wps:if> tag.

 

<wps: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 <wps:url/> tag.

Attributes

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

    In the logged-in mode, URLs carry a request ID to allow proper sequencing of the requests. Requests with outdated IDs are not executed anymore. To allow out-of-sequence requests, the value of "no" or "false" turns off sequence checking for this URL.

  • 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 and 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 showTools if attribute 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='<wps:url commandParam="requestParamName"/>'>
    
      <select name="requestParamName" 
              onchange="javascript: this.form.submit(); ">
    
          <wps:someLoop>
    
            <option value="<%= theUrl %>" >Some title goes here
    
          </wps: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 <wps:url> tag to process input fields, user ID, and password.


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

 

<wps:urlFind>

Generates a URL pointing to a file. The resource is searched under different paths depending on the markup and locale supported by the client and the specified attributes of the tag.

Attributes

  • root="root"

  • path="path"

  • file="file"

    This attribute is required

  • allowRelativeURL="true|false"

The first place where the resource is found is used to construct the URL. The search order used is:

  1. root path

  2. markup name

  3. path

  4. markup version

  5. locale in diminishing sequence

  6. file name

See Aggregation concepts for more information about how the portal server locates resources. The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. See Generating relative URLs for more information.

 

<wps:urlFindInSkin file="file_name" id="identifier">

Similar to <wps:urlFind>, this tag generates a URL pointing to a file in...

was_root/installedApps/hostname/wps.ear/wps.war/skins

The skin is taken from the user's or system's settings. The file attribute is required.

When id is specified, the tag initializes a scripting variable with the value normally written out and nothing is written to the output stream. The value of the id attribute is the name of the scripting variable.

 

<wps:urlFindInTheme file="file_name" id="identifier">

Similar to <wps:urlFind>, this tag generates a URL pointing to a file in...

was_root/installedApps/hostname/wps.ear/wps.war/themes

The theme is taken from the user's or system settings. The file attribute is required.

When id is specified, the tag initializes a scripting variable with the value normally written out and nothing is written to the output stream. The value of the id attribute is the name of the scripting variable.

 

<wps:urlGeneration attribute="value">>

Create a URL to pages or portlets using page or portlet unique name or ID. 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 <% wpsURL %> scripting variable can be used to write the URL directly to the output stream. For example:

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

Attributes

  • accessControlCheck="CreatePage|EditLayout|DeletePage|AssignRoles|NoCheck"

    Indicates the permissions to be checked. 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"

    indicates the 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:urlGeneration actionName="myAction" 
             contentNode="my.ContentNode" 
             layoutNode="my.LayoutNode">
    
     <a href="<%wpsURL.write(out)%>">Link to portlet with myAction</a>
    
     </portal: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"

    Indicates 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.properties.

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

    Indicates the 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.

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

  • 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"

    Indicates the 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.

  • 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 <wps: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.

  • useReqID="true|false"

    Determines whether a request ID is appended to the URL. This can be used to open a new browser window while preserving the validity of the links. Indicates if the request ID should be added to the URL. Default is true.

See Creating URLs from themes and skins for examples.

 

<wps:urlParam name="parameter_name" value="parameter_value">

Add parameters to the parent URL. Parent tags include <wps:url/> and <wps:urlGeneration/>. Parameters added to the <urlGeneration/> tag occur as unscoped query parameters unless the attributes specified on <urlGeneration/> 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 JSR 168 compliant portlets if the URL does not point specifically to that portlet.

Attributes

  • name

    Required. Indicates the name of the parameter.

  • value

    Required. Indicates the value of the parameter.

  • type

    Optional. Indicates one of the following types:

    • render - the parameter is available as a render parameter for the portlet.

    • action - the parameter is available as an action parameter for the portlet.

    • query - the name value pair is added to the URL as a query parameter. This is the default value if type is not specified.

 

<wps:urlParent allowRelativeURL="true|false" />

This tag creates a URL that supports one of the following surrounding tags. For better performance, use the parent tag's scripting variable if one is available.

The allowRelativeURL attribute indicates whether a fully-qualified or relative URL is generated. The default is set by the com.ibm.portal.state.accessors.url.URLContext.enableRelative property in StateManagerService.properties.

 

<wps:user attribute="value"/>

If the user is logged in, this tag returns one of the specified user attributes. value can be any user attribute defined to Member Manager.

 

 

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.