Changing the Appearance of Service Provider End User Pages

The Apache Struts Action framework provides navigation between the pages, while the Struts/Tiles templating framework is used to create common look and feel for the application.

Modifying the Layout

The Service Provider User Interface pages implement the Apache Struts Action framework and Tiles to control page layout. The file $WSHOME/spe/user/common/layouts/page.jsp is used as a template when pages are rendered, with various regions of the page corresponding to the output of individual JSPs or tiles. The default page template consists of four tiles:

masthead
navbar
subnavbar
content

Adding a new tile, for example a “footer” at the bottom of the page, is accomplished by defining the tile in $WSHOME/WEB-INF/spe/config/tiles-page-defs.xml and then inserting the tile in page.jsp:

<body class="DefBdy" onload=’checkFirst( );’>
   <tiles:insert attribute="masthead" ignore="true"/>
   <tiles:insert attribute="navbar" ignore="true"/>
   <tiles:insert attribute="subnavbar" ignore="true"/>
   <tiles:insert attribute="content"/>
   <tiles:insert attribute=”footer” ignore=”true”/>
</body>

Placement of the tile on the rendered page can be controlled via HTML markup in the page template and/or via CSS. A template tile for a page footer is located at $WSHOME/spe/user/common/tiles/footer.jsp.

Another page which users will frequently want to modify is the login page. This page consists of a single tile, content, whose source JSP is $WSHOME/spe/user/Login.jsp. The actual HTML <FORM> is generated as an Oracle Waveset form, but it is wrapped in content from Login.jsp.

The page.jsp file includes three CSS stylesheet files:

styles/lockhart.css
styles/style.css
styles/customStyle.css.

The first two stylesheets are the system defaults and should not be modified, as they may be rewritten during upgrades. The customStyle.css stylesheet is empty and is intended for user custom CSS styles. These files are all located in $WSHOME/spe/user/common/layouts/styles/.

The Service Provider User pages are designed so that rebranding the page can be accomplished by modifying CSS styles, rather than JSPs. For example, the product name logo (Java System Waveset Service Provider) image in the masthead is specified by the following CSS definition:

td.MstTdTtlProdNam {
   background: url(../images/ProductName.png) no-repeat 10px 30px;
   padding:10px 10px 0px 10px;
   vertical-align:top;
   white-space:nowrap;
   height: 75px;
   width: 520px;
}

You can override this definition in customStyle.css to point to a different image file or specify a different location. For more information about using CSS to change user interface elements in Oracle Waveset, see Deployment Guide.

Internationalization and Localization

Service Provider uses a standard Java message resource bundle for display strings in the UI. This resource bundle is normally included in the idmspe.jar file and must be extracted if you plan to customize message strings for display in the default en_US locale.

$ cd $WSHOME/WEB-INF/classes
$ jar xvf ../lib/idmspe.jar com/sun/idm/idmx/msgcat/IDMXMessages.properties

The format of the resource bundle is the standard key =value format. In the example page.title.home=Home , page.title.home is the key and Home is the value associated with the key. The value string may be parameterized as standard java.text.MessageFormat strings.

There are two types of message keys in the resource bundle: those used by Struts/Tiles and those used by the Waveset forms engine. Keys recognized by Struts/Tiles will NOT be recognized by the Oracle Waveset forms engine, and vice versa.

Struts/Tiles message keys use the “dot notation” format, such as page.title.home. Message keys for the Waveset forms engine and for email notification templates must contain an underscore character and no spaces, such as IDMX_login_field_username. For more information on using the Waveset forms engine keys, see Deployment Guide.

For locales other than en_US, the resource bundle file contains the same key values as the default file and appropriate value string translations. For example, the message resource bundle strings for the fr_FR locale would go in $WSHOME/WEB-INF/classes/com/sun/idm/idmx/msgcat/IDMXMessages_fr_FR.properties .

Localization and Email Templates

Message bundle keys may also be used in email templates. The default Service Provider End-User email templates are stored in the repository and have IDs similar to #ID#EmailTemplate:SPEEndUserChangePassword . Message bundle keys may be specified for the email subject and body of the message:

<!-- The template used when user changes their password. -->
<EmailTemplate id=’#ID#EmailTemplate:SPEEndUserChangePassword’
name=’Service Provider End-User Change Password’ 
displayName=’UI_EMAILTEMPLATE_SPE_END_USER_CHANGE_PASSWORD’
smtpHost=’$(smtpHost)’ fromAddress=’admin@example.com’>

   <subject>IDMX_change_password_email_subject</subject>
   <body>IDMX_change_password_email_body</body>
   <MemberObjectGroups>
      <ObjectRef type=’ObjectGroup’ name=’All’/>
   </MemberObjectGroups>
</EmailTemplate>

Note that message bundle keys used in email templates MUST contain an underscore character to be recognized as a message key.

Localizing Strings in the Navigation Bars and Page Titles

Strings that appear in the horizontal navigation bars and browser title are handled by the Struts framework and are referred to by message keys in the resource bundle which use the “dot notation” naming convention.

For example, to change the subnavigation tab for “Password” (under the “My Profile” tab) to use the string “My Password” we must first look up the message bundle key. This is defined in $WSHOME/WEB-INF/spe/config/tiles-tab-defs.xml :

<!-- Unselected sub-navigation tab for changing the user’s password -->
<definition name=".subnav_tab.Password" extends=".subnav_tab.Base">
   <put name="button_link" value="/spe/user/protected/ChangePassword.do?newView=true" />
   <put name="button_label_key" value="nav.tab.label.password" />
</definition>

In this case, the message bundle key nav.tab.label.password is used for the (en_US) string “Password” which will appear as the tab label text. See above for how to extract and modify the message resource bundle file.

Note that the above Tile definition extends a definition called .subnav_tab.Base , which is defined as follows:

<!-- Base type for unselected sub-navigation tabs -->
<definition name=".subnav_tab.Base" path="/spe/user/common/tiles/subnav_tab.jsp" 
controllerClass="com.sun.idm.idmx.web.LocalizeButtonLabel">
   <put name="button_link" value="${button_link}" />
   <put name="button_label_key" value="${button_label_key}" />
   <put name="link_class" value="Tab2Lnk" />
</definition>

We are passing the parameter ${button_label_key} a specific value of “nav.tab.label.password” in the .subnav_tab.Password definition. The base tile definition has a controller class associated with it called com.sun.idm.idmx.web.LocalizeButtonLabel . The purpose of this controller class is to take the value of parameters passed to it, like button_label_key, look them up in the message bundle and put the resulting string back into the Tiles context so that they may be referred to in the rendering Tile. The JSP which renders an unselected subnavigation bar tab, subnav_tab.jsp, looks like:

<%@ taglib uri="/tags/struts-tiles" prefix="tiles" %>
<%@ taglib uri="/tags/spe" prefix="spe" %>
<tiles:useAttribute name="button_link"/>
<tiles:useAttribute name="button_text"/>
<tiles:useAttribute name="link_class"/>
<td><a href="<%=request.getContextPath()+button_link%>" tabindex="<spe:counter/>" 
class="<%=link_class%>"><%=button_text%></a></td>

Note that the controller puts the message bundle string back into the Tiles context as the attribute button_text.

A similar technique is used to define the strings which will appear as titles and subtitles on pages which are simple Struts forms (as opposed to a “form” created by the Waveset forms engine). An example of a Struts form is the OperationResult page. This page displays the results of an operation like changing a user’s password or notification address. A controller class called com.sun.idm.idmx.web.LocalizePageTitles is associated with the base tile definition for this page. This controller class may be passed message bundle keys for the page title:

<!-- Page showing success message after a user resets the password. -->
<definition name=".page.ResetPasswordSuccess" extends=".page.OperationResultNoAuth">
   <put name="forward_id" value="ResetPasswordSuccess" />
   <put name="page_title_key" value="page.title.password_reset_success" />
   <put name="page_subtitle_key" value="page.subtitle.password_reset_success" />
</definition>

OperationResult Relay Definition

When a user resets a password or changes the user ID in Service Provider, the results of the operation are displayed to the user. Instead of creating a separate JSP for each successful operation, it is desirable to have a generic OperationResult page that contains the following:

The title and subtitle of the page
The appropriate information that indicates the user’s change was successfully applied to the directory
The page (URL) should the user go to after acknowledging the “success” message.

The title and subtitle strings are inserted into the page $WSHOME/spe/user/OperationResult.jsp . We would also like to be able to pass a key from the tile definition to look up the appropriate action forward for the user’s final destination.

<put name="forward_id" value="ResetPasswordSuccess" />

When the .page.ResetPasswordSuccess tile is rendered, the forward_id parameter is added to the form as a hidden field with name dispatch.

When the user acknowledges the result by clicking the OK button, the following action is executed:

<!-- Set action forward mapping to final destination forward -->
<action path="/spe/user/OperationResult" name="resultForm"
      type="com.sun.idm.idmx.web.RelayAction" scope="request"
      validate="false">
   <forward name="ForgotUsernameSuccess" path="/spe/user/Login.do?newView=true" 
      redirect="true"/>
   <forward name="PasswordEmailed" path="/spe/user/Login.do?newView=true" 
      redirect="true"/>
   <forward name="ResetPasswordSuccess" path="/spe/user/Login.do?newView=true" 
      redirect="true"/>
   <forward name="ProfileLocked" path="/spe/user/Login.do?newView=true" 
      redirect="true"/>
   <forward name="ProfileHasBeenLocked" path="/spe/user/Login.do?newView=true" 
      redirect="true"/>
   <forward name="EnrollSuccess" path="/spe/user/Login.do?newView=true" 
      redirect="true"/>
</action>

The com.sun.idm.idmx.web.RelayAction class looks up the dispatch request parameter value in the above definition and forwards to the associated URI. In our case, ResetPasswordSuccess maps to the URI ”/.m”/spe/user/Login.do?newView=true”.

Error Handling

In general, errors from which the user can recover, such as form validation errors, are displayed on the edit form so the user can correct the data and resubmit the form.

Errors encountered during processing are generally not recoverable and must be handled differently. A generic error action forward, spe/user/Error.do , is used to display a message that the user should report the error to their local administrator. The JSP supporting this action, $WSHOME/spe/user/Error.jsp , will also include any exception stack trace information in the rendered page source as an HTML comment.

Previous: Using Apache Struts to Create User Pages