. 29
( 87 .)


If navigation is to be used, include PlaceBarInclude.jsp, providing
the next level of navigation below the top-level one (for example, within
My Portal, between Welcome and the other options), and PageBarIn-
clude.jsp provides the next level of navigation. Obviously, by removing
the JSP include statements for either of these ¬les, you can remove this level
of navigation altogether from a speci¬c theme.
WY009-08 WY009-BenNatan-v1.cls May 9, 2004 15:56

156 Chapter 8

These pages provide speci¬c implementation of a general concept in Web-
Sphere Portal, which is navigation. Using the <wps:navigation> tag you
can de¬ne your own navigation menus, which are not necessarily limited
to two or three levels down.

<%-- Don't show navigation in solo mode --%>
<wps:if portletSolo="no">
<%@ include file="./PlaceBarInclude.jsp" %>
<%@ include file="./PageBarInclude.jsp" %>
<td width="100%" height="100%" valign="top" colspan="2">
<a name="wpsMainContent"></a>

We conclude with a product-speci¬c PageEndInclude.jsp.

<%@ include file="./extension/PageEndInclude.jsp" %> <%-- This
includes Extend/Express specific page logic. --%>

An important caveat to note about included ¬les is that if you change
them, you need to make the Portal Server aware of this by modifying the
Default.jsp command (for example, using the UNIX touch command).
Using the WPS tags, you may create intricate logic to customize your por-
tal. WebSphere Portal provided dozens of other tags, which are available.
These tags are described in the next section.

Portal JSP Tags
In the previous section you saw how the tags wps:constants, wps:text,
wps:screenRender, wps:navigation, and wps:if are used.
The Portal Server provides many more JSP tags. The taglib ¬le for these
tags is called engine.tld and is located in the <WPS ROOT>/shared\app
\WEB-INF\tld directory. The main purpose of these JSP tags is to allow the
JSP designer to leverage some of the information and capabilities available
inside the Portal Server engine.
The remainder of this section describes some of the more commonly used
JSP tags provided by the Portal Server. A full list can be found in the IBM
product documentation.
WY009-08 WY009-BenNatan-v1.cls May 9, 2004 15:56

Tailoring the Portal Web Design 157

The most commonly used portal JSP tag is wps:if. In the Default.jsp
listing above you saw how to use it with the portletSolo attribute, which
checks whether the portlet is in solo state. There are a multitude of other
conditions that can be checked:

capableof="capability". Tests whether the client has a speci¬c
capability (for example, HTML 4 0, HTML FRAME).
locale="locale". Tests for a speci¬c locale (for example, in US).
The notLocale="locale" attribute checks if the locale is different
than the one speci¬ed. The notLocale form is required as the
syntax of the wps:if tag does not allow for fully blown logical
loggedIn="yes|no". Tests whether the user is logged in. This
condition is used extensively in Toolbarinclude.jsp, discussed
in the next section.
navigationAvailable="yes|no". Tests the availability of
newWindow="yes|no". Tests whether portlet is running in a
separate browser window.
screen="screen". Checks if the current screen is the one speci¬ed.
There is also a notScreen version available.
pageAvailableNext="yes|no". Checks if there is a following
page available. A similar tag pageAvailablePrevious checks for
the availability of a previous page. Both of these are used in
Banner.jsp to add a scroll icon allowing the user to access
additional tabs if all of them are not visible concurrently.
pageCompletelyActive="yes|no". Tests if the current page and
its parents are all active.
pageBookmarkable="true|false". Tests if a page can be
bookmarked (as per the de¬nitions in the administrator™s Manage
Pages). This condition can be used to enclose a bookmark link.
portletMaximed="yes|no". Tests if the portlet state is
portletMode="edit|view|configure|help". Tests what modes
the portlet supports. This is important for the title bar display in
customized skins.
showTools="yes|no". Tests whether additional controls should be
placed in the portlet title bar (usually, clicking the wrench icon in the
top-level toolbar sets this to yes).
WY009-08 WY009-BenNatan-v1.cls May 9, 2004 15:56

158 Chapter 8

resumeLevel="0|1|2". Tests for the setting of the level of session
preservation as set by the administrator (0 means no persistent
session state, 1 means portlet states and modes are stored, and 2
means all portlet settings are stored).
resumeOption="0|1" . Tests whether users are being offered to
restore their most recent session upon login. 0 means no, 1 means yes.

In addition to the wps:if tag, there is a negative wps:unless tag. With
this tag, if any of the conditions is true, the following text is not written to
the output page.
In order that you are able to access ¬les and resources, the Portal Server
provides the tags wps:urlFind, wps:urlFindInSkin, and wps:url
FindInTheme. All three have a file=" filename"attribute. The urlFind
also has path and root attributes to specify where to look for a ¬le, and the
other two just have an id attribute, which allows you to place the URL into
a scripting variable instead of to the output stream. All forms of urlFind
use the hierarchical search sequence described earlier, and thus depend on
the locale and markup of the client.
While urlFind is suf¬cient for accessing static resources, you need to use
wps:urlGeneration to generate URLs for portal pages. This tag places
the generated URL into a variable wpsURL and has attributes called root,
navigationNode, contentNode, and compositionNode used to iden-
tify the node where the page or portlet is located. Other attributes available
with this tag are as follows:

portletWindowState="maximized|solo|normal". Indicates
the state of the portlet window when it is displayed. This is only
applicable to portlets.
Roles|NoCheck". Indicates what kinds of permissions are required
from the users and should be checked. If NoCheck is speci¬ed, no
checks are made.
useReqID="true|false". This attribute determines whether a
request ID is appended to the URL. By default this is true, thus
allowing users access to a new browser window without the links
getting invalid.
newWindow="true|false". Opens a new window or new iFrame.

If you need to pass parameters to a generated URL, <wps:urlGeneration
/> together with <wps:urlParam/> can be used. The latter tag has two
attributes: name specifying the parameter name and value specifying the
parameter value.
WY009-08 WY009-BenNatan-v1.cls May 9, 2004 15:56

Tailoring the Portal Web Design 159

Some other tags are as follows:

wps:date, d wps:time. These can be used to insert the date and
time in various formats.
<wps:user attribute="userID|fullName|familyName">.
Returns an identi¬cation of the user based on the attribute, if the user
is logged in.
<wps:captureContext contextKey="context">. Captures
the content of the tag (that is, whatever is placed between the tag
beginning and ending markers) and places as a string attribute in
PageContext. This is useful when you need to use data, which can
only be generated by JSP tags from within JSP Java code.

Adding Top-Level Links
Recall that during our review of the Default.jsp page, the ¬le
ToolbarInclude.jsp was included to control the top-level navigation.
In order to enable the “New Portal” entry de¬ned at the end of the previous
chapter, you need to understand how navigation works. To this end, let™s
take a look at TooBarInclude.jsp. For brevity, some of the comments
were removed, and we only show the code for the ¬rst two navigation
buttons. The code for each is denoted by a comment.

<table border="0" cellspacing="0" cellpadding="0" >
<%@ page import="com.ibm.portal.*"%>
<%-- My Portal button --%>
<wps:if loggedIn="yes" portletSolo="no">
<td class="wpsToolBar" nowrap><b>
<wps:text key="link.my.portal" bundle="nls.engine"/></b></td>
<%-- Administration button --%>
<wps:if loggedIn="yes" portletSolo="no">
<wps:urlGeneration contentNode="wps.Administration"
<td class="wpsToolBar" valign="middle" align="<%=bidiAlignRight%>"
<a href="<% wpsURL.write(out); %>"
class="wpsToolBarLink"><wps:text key="link.administration"

What you can see is that if the user is logged in, and the portlet mode is
not solo, the JSP provides button linking to My Portal. Notice this link
WY009-08 WY009-BenNatan-v1.cls May 9, 2004 15:56

160 Chapter 8

has no href tag, since it is only used within the portal and not from the
administration pages.
The Administration button does sport an actual link using an href tag
obtained by using the generateURL tag.
In order to provide buttons for top-level New Portal label, we may add
the following and replace the code after the My Portal button with the

<%-- New Portal button --%>
<wps:if loggedIn="yes" portletSolo="no">
<wps:urlGeneration contentNode="wps.New Portal"
<td class="wpsToolBar" nowrap>
<a href="<% wpsURL.write(out); %>" class="wpsToolBarLink">
New Portal</a>

Once you implement this change, you have a new button allowing you to
navigate to the new top-level page. However, once users go there, they have
no way to return. To tackle this dif¬culty, you must create a different theme
for the New Portal label, and implement there ToolBarInclude.jsp. The
implementation should be such that the New Portal button is boldfaced in-
stead of the My Portal button, but the latter would have a link. Incidentally,
this is exactly the reason for having an Admin theme preinstalled with the
Portal Server. You can notice that when entering the Admin mode the Ad-
ministration button becomes bold and the My Portal button becomes active.
To have the New Portal button available from the administration mode, this
theme needs to be modi¬ed as well.
In some cases, it is desired to use different screens, especially for top-
level links. For example, in the preinstalled themes, a different screen is
used for logging in or for users who have forgotten their password. The fol-
lowing excerpt from ToolBarInclude.jsp shows the code for the “for-
got password” button. This code uses the wps:url tag with the screen

<%-- forgot password button --%>
<wps:if loggedIn="no" notScreen="ForgotPassword">
<td class="wpsToolBar" valign="middle" align="<%=bidiAlignRight%>"
<a class="wpsToolBarLink"
href='<wps:url screen="ForgotPassword" home="public"/>'><wps:text
key="link.password" bundle="nls.engine"/></a>


. 29
( 87 .)