IBM R1 User Manual

soft ware

Learning Management System R1

Customization Guide June 2003

Disclaimer

THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, IT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTHING CONTAINED IN THIS DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF IBM SOFTWARE.

Licensed Materials - Property of IBM

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GS ADP Schedule Contract with IBM Corp.

Lotus Software IBM Software Group One Rogers Street Cambridge, MA 02142

List of Trademarks

IBM, the IBM logo, AIX, AS/400, DB2, LearningSpace, LearningSpace Forum, IBM Directory Server, RS/6000, iSeries, xSeries, MQSeries, Cloudscape, Netfinity, OfficeVision, OS/2, OS/390, OS/400, S/390, Tivoli, WebSphere, 1-2-3, cc:Mail, Domino, Domino Designer, Freelance Graphics, iNotes, Lotus, Lotus Discovery Server, Lotus Enterprise Integrator, Lotus Mobile Notes, Lotus Notes, Lotus Organizer, LotusScript, Notes, QuickPlace, Sametime, SmartSuite, and Word Pro are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both.

Crystal Reports is a registered trademark of Crystal Decisions Corporation in the United States, other countries, or both.

Pentium is a trademark of Intel Corporation in the United States, other countries, or both.

Java, JavaServer Pages, JavaBeans, JavaScript, J2EE, JDBC, Sun Enterprise, and Sun Solaris are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

JReport and JReport Designer are trademarks of Jinfonet Software, Inc. in the United States, other countries, or both.

Macromedia, Pathware, and Dreamweaver are registered trademarks of Macromedia, Inc. in the United States, other countries, or both.

Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries.

Oracle is a registered trademark of Oracle Corporation in the United States, other countries, or both.

PKZIP is a registered trademark of PKWARE, Inc. in the United States, other countries, or both.

SmartForce is a trademark of SkillSoft Corporation in the United States, other countries, or both.

SQL Server and Internet Explorer are trademarks of Microsoft Corporation in the United States, other countries, or both. Windows, Windows NT, Active Directory, and Outlook are registered trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other product, company, and service names mentioned herein may be the trademarks, registered trademarks, or service marks of their marks of their respective owners.

Table of Contents

Chapter 1 Customizing the IBM Lotus Learning Management System User

interface ...........................................................................................................................1

A disclaimer and a word about conventions.......................................................................................2

Acronyms and abbreviations................................................................................................................. 2

Chapter 2 Changing settings through the user interface or XML ..............................5

Chapter 3 Controlling access to features through permissions ................................ 7

To add a role to the system .................................................................................................................... 7

To modify permissions settings for an existing role........................................................................... 8

To assign a role to a user ........................................................................................................................ 8

To automatically assign a role to a user ........................................................................................... 8

To explicitly assign a role to a user ................................................................................................... 8

Chapter 4 Customizing Help ........................................................................................ 11

The Anatomy of a Help topic............................................................................................................... 11

Editing an existing Help topic ............................................................................................................. 16

Replacing a context-sensitive Help topic ........................................................................................... 16

Adding your own Help topic............................................................................................................... 17

Chapter 5 Customizing JavaServer Pages ................................................................. 19

Overview ................................................................................................................................................ 19

LMS JSP tag libraries......................................................................................................................... 20

The Anatomy of a JSP ....................................................................................................................... 23

Making global changes ......................................................................................................................... 31

Applying customization sets............................................................................................................ 32

Changing the application style........................................................................................................ 32

Updating page text............................................................................................................................ 35

Adding and replacing graphics....................................................................................................... 36

Changing individual JSPs..................................................................................................................... 38

Changing the style of an individual JSP.........................................................................................38

Changing the functionality of an individual JSP........................................................................... 39

Chapter 6 Customizing Search .................................................................................... 45

Customizing user searches................................................................................................................... 45

Adding LDAP attributes to User Search pages............................................................................. 45

Removing fields from User Search pages....................................................................................... 46

Customizing Offerings Catalog searches ........................................................................................... 47

Adding custom fields to the Offerings Catalog............................................................................. 47

Removing fields from Offerings Search pages.............................................................................. 47

Customizing course management and resource searches ............................................................... 47

Table of Contents iii

Removing fields from the Search pages ......................................................................................... 48

Chapter 7 Customization sets...................................................................................... 49

Creating a customization set................................................................................................................ 49

Installing a customization set on the Offline Learning Client......................................................... 54

Chapter 8 Creating a tab............................................................................................... 57

The Users page....................................................................................................................................... 57

users.jsp............................................................................................................................................... 58

navigation.xml ....................................................................................................................................... 62

The <module>, <trail>, and <step> tags: main pages and linked pages................................... 64

The <name> tag: page names and resourced text......................................................................... 65

The <target> tag: struts action-mapping........................................................................................ 65

The <content> tag: JSP file names ................................................................................................... 65

The <label> tag: breadcrumbs ......................................................................................................... 65

The <title> tag: title bar text............................................................................................................. 67

The <permissions> tag: permission to display the page.............................................................. 67

The <helpPage> tag: context-sensitive Help.................................................................................. 67

Adding custom permissions ................................................................................................................ 67

Example .................................................................................................................................................. 71

Index............................................................................................................................... 87

iv IBM Lotus Learning Management System Release 1 Customization Guide

Chapter 1 Customizing the IBM Lotus Learning Management System User interface

There are several ways you can tailor the IBM® Lotus® Learning Management System (LMS) interface to control the product's look and feel and the user's access to its features. Depending on the nature of the changes you want to make, customization can involve one or more of the following:

• Changing default settings that affect what the user can see and do. You can do this either through the Administrator interface or by editing XML files.

• Editing properties, template, graphics, and style sheet files.

• Editing the HTML files that constitute the Help system.

• Editing the application’s JavaServer Pages™ (JSPs)changing the HTML content, adding

or removing custom tags or overriding the default settings of their attributes, adding or changing functionality by including Java™ code or JavaScript™, adding or removing

include statements, inserting or changing forward statementsor writing your own.

• Copying and renaming portions of the directory tree on the Learning Management

Module server (LMMS) and Delivery server (DS) and editing the copied files to create a new interface. (The aggregation of such copied and edited files, together with the information necessary to locate the files and identify the set of users to whom they apply, is known as a customization set.)

• Creating custom reports. (This process is described in the Administrator’s Guide.)

• Writing directly to the LMS database.

This document describes the aspects of the Student interface that you can customize without having to write directly to the LMS database or program in Java. The LMS database schema is described in the Administrator's Guide.

Note: If you are upgrading to the LMS from a version of LearningSpace® that you have customized, changes that you made to the LearningSpace interface will be lost because the implementations of the two applications are radically different. Changes that you make in the LMS interface may be lost when you upgrade to subsequent versions of the product or reinstall the current version. It is therefore advisable to save backup copies of all files that you customize.

The user interface consists of a number of JSPs whose visual attributes you can modify. These visual attributes include the following:

• static text

• colors and fonts

• graphical images

• background colors

• frame dimensions

Chapter 1: Customizing the user interface 1

Static text is resourced in .properties and .txt files in the properties (and, in the case of the LMM server, templates) directories for the LMM and Delivery servers and the Offline Learning Client (under source\resources). These directories contain resource bundles for the various languages that the LMS supports.

Colors and fonts are typically specified in a Cascading Style Sheet (CSS) file. CSS files are grouped by browser type (under Web\<server>\css\<language>\<browser>, for example, Web\LMM\css\en\styInternetExplorer5).

Graphical imagesGIF and JPEG filesreside in the images directory for the LMM and Delivery servers and the Offline Learning Client in the web directory (for example, web\LMM\images).

As suggested earlier, you can modify a JSP’s functionality as well as its display attributes, by editing the JSP itself. The JSP files for the web\LMM server, Delivery server, and Offline Learning Client reside in the web\LMM, web\ds, and web\duc directories, respectively.

A disclaimer and a word about conventions

This document is not an exhaustive description of all the ways in which you can customize the LMS. Rather, it covers a broad range of changes that customers typically want to make to the application to customize its look and feel and control users’ access to features.

Some changes that you can make to the application are specific to a particular window, while others are system wide. For example, if you change the text of the aboutLMM.title property in the ApplicationResources.properties for the LMM, this will affect only one JSP (aboutLMM.jsp). However, if you change the text of, say, the button.cancel property in the ApplicationResources.properties for the LMM, this change will be realized in all the LMM JSPs that have a Cancel button. Examples in this document remark on this distinction only where it might not be obvious.

As mentioned previously, the application’s CSS files are browser-specific, one set being for use with Internet Explorer™ and another for use with Netscape®. These two sets of style sheets do not differ significantly from each other; they differ in their details. Rather than show changes for both style sheets, the examples in this document refer to the style sheets for Internet Explorer, with the understanding that the examples could, with minor adjustments, apply equally well to the style sheets for Netscape.

Note: When you edit a CSS file, your changes should appear in the interface the next time the user logs on. (If not, emptying the user's browser's cache should remedy the situation.) When you edit a .properties file, however, you need to stop and restart the Web Publishing Service for your changes to take effect. The reason for this difference is that CSS files are processed immediately by the client, while .properties files are processed by Java code on the server.

Acronyms and abbreviations

The following table contains a list of possible unfamiliar acronyms and abbreviations used in this document or appearing in the directory tree, or both:

2 IBM Lotus Learning Management System Release 1 Customization Guide

Acronyms and abbreviations

Acronym or

What it stands for

Abbreviation

CSS Cascading Style Sheet DS Delivery Server DUC Offline Learning Client (Disconnected Use Client) EAR (file) Enterprise Archive (file) JSP JavaServer Page LDAP Lightweight Directory Access Protocol LMM Learning Management Module LMMS Learning Management Module Server LMS Learning Management System (can refer either to the application or just to the

LMM) LMSS Learning Management System Server (same as LMMS) SSO Single Sign-on TLD (file) Tag Library Descriptor (file) WAR (file) Web Application Archive (file) WAS WebSphere Application Server WPS WebSphere Portal Server

Chapter 1: Customizing the user interface 3

4 IBM Lotus Learning Management System Release 1 Customization Guide

Chapter 2 Changing settings through the user interface or XML

You can customize the application by changing various of the settings that are established when you first install and configure the system. There are three ways to do this:

• Edit one or more of the XML files in which initial system values are stored.

• Enter or change values in the Settings module of the Administrator interface.

• Edit the application database directly, changing the appropriate record in the

application_setting table.

When you install and configure the application, a number of XML files receive values that determine such things as where the application looks for Help files, what the initial settings are for user preferences (such as time zone, language locale, and whether to display hover Help), the maximum number of entries to include in an LDAP search result set, and so on. You can change these initial settings by editing these files, which reside in the classes directory.

The three XML files of most interest are settings.xml, ds-settings.xml, and duc-settings.html. The first of these controls settings on the LMM server; the second controls settings on the Content Delivery server; and the last applies to the Offline Learning Client.

Here is what the preferences settings section of settings.xml looks like:

================================================================

PreferenceSettings

default user preference settings component

================================================================

-->

<preferences component="com.lotus.elearn.settings.PreferenceSettings"

timezone="EST" language="en" locale="en_US" tooltips="yes" recordPerPage="10" calendarState="viewMonth" primaryCalendar="gregorian" secondaryCalendar="gregorian" datepickerCalendar="gregorian" firstDayOfWeek="1" />

<!--

================================================================

ds-settings.xml looks much the same as settings.xml in this example. There is no comparable entry in duc-settings.html (because in this case the client gets its settings from settings.xml).

In any case, you can change the attribute values in these XML files by editing the files with a text editor and then stopping and restarting the server. If you change settings.xml, you should change ds-settings.xml and, where relevant, duc-settings.xml as well.

However, editing the XML files is not the preferred way to change system settings. Where possible, using the Administrator interface to make changes is both simpler and less apt to result in unwanted inconsistencies between server settings. (Not all settings that you might want to change are exposed through the Administrator interface, but most of them are.)

So, for example, to make global changes in preferences, you can click the Settings tab in the Administrator interface, click LMM Server, General Settings, and then User Defaults and enter the desired new values. These will override the settings in the XML files.

Chapter 2: Changing settings 5

Changes that you make through the Administrator interface are written to the application_setting table in the application database and take precedence over settings in the XML files. If you want to revert to the values in the XML files, you need to delete the relevant record(s) in the application_setting table.

Note: users can have the last word on preferences settings by making changes through the Preferences dialog box, which they can invoke from the Navigation bar. Thus, the settings that a user specifies in the Preferences dialog box override settings that an administrator has made in the Settings module (which in turn override the defaults specified in settings.xml).

6 IBM Lotus Learning Management System Release 1 Customization Guide

Chapter 3 Controlling access to features through permissions

You can limit or expand users’ access to the application’s features and functionality by setting the permissions that define the roles that you assign to those users. These roles can either be ones that come prepackaged with the application (Anonymous, Student, Administrator, Instructor, and Manager) or ones that you create yourself. The Course Administrator Help system and the System Administrator Guide explain how to create, modify, and assign roles to users.

There are two ways to assign a role to a user:

• You can assign a role automatically, by matching string. That is, the role is automatically assigned to all the Learning Management System users who are identified in the LDAP directory by the matching string you specify. The assignment automatically applies to current Learning Management System users and to new users when they are added to the Learning Management System database.

• You can assign one or more roles to existing the Learning Management System users interactively.

Both of these methods are described below.

When you assign multiple roles to a user, the user enjoys the union of the privileges for those roles. For example, by default, a user assigned the Student role doesn’t have permission to run reports. By default, a user assigned the Instructor role does have permission to run reports. Assuming that you don’t change the default settings, if a user is assigned both roles, he or she has permission to run reports.

The Anonymous role is a special case. When users initialize the application, they are assigned the Anonymous role until such time as they log in or exit. When users log in, the Anonymous role no longer applies to them. So, for example, if you were to change the permissions for the Anonymous role to allow anonymous users to run reports (not that you probably would), users whose sole role is Student who ran the application could run reports until they logged in, after which they couldn’t because their privileges as Anonymous had been discarded when they logged in.

Automatically assigned roles are a somewhat different special case. If you automatically associate a role with the set of users in the LDAP directory that are identified by a matching string, you can’t override this assignment for a user by running the application, locating the user, and changing his or her role assignments. For example, if everybody in your LDAP directory identified by the string *,ou=Cambridge,o=IBM is automatically assigned the role of Student and you want to remove this role assignment from user John Doe who is identified by that matching string and assign him the role of Instructor instead, you need to either change the user’s LDAP record so that the user is no longer identified by the matching string or change the matching string that identifies the users to whom you want to automatically assign the role.

That being said, the following sections are a reminder for how to add a role to the system, change the permissions for an existing role, and assign a role to a user.

To add a role to the system

1. Open the Administrator interface.

2. Click the Users tab.

3. Click Manage Roles.

4. Click Add Role.

Chapter 3: Controlling access to features 7

5. Enter the name of the new role and a description, and then click Save. This adds the role to the role list.

6. Click the name of the new role in the list. This displays the Role Details page.

7. Check the permissions you want to grant to users assigned this role in the various categories you can select from the category drop-down box.

To modify permissions settings for an existing role

1. Open the Administrator interface.

2. Click the Users tab.

3. Click Manage Roles.

4. Click the name of the role whose permissions you want to reset.

5. Check the permissions you want to grant to users assigned this role in the various categories you can select from the category drop-down box.

To assign a role to a user

As mentioned previously, there are two ways to assign roles to users: explicitly or automatically. The first method involves searching for users in the system, selecting the ones to whom you want to assign a role, and assigning them that role. The latter method involves specifying a matching string and letting the application assign the users identified by that string the role you specify.

To automatically assign a role to a user

1. Open the Administrator interface.

2. Click the Users tab.

3. Click Manage Automatic Assignments. The application displays a list of existing roles.

4. Click the role that you want the application to automatically assign to users in the LDAP directory.

5. Click Add Automatic Assignment, select a match type (Name, Attribute, or Group), and enter the matching string to be used in identifying users in the LDAP directory to whom you want to assign the selected role.

6. Click Add.

To explicitly assign a role to a user

1. Open the Administrator interface.

2. Click the Users tab.

3. Click Manage Users. The application displays the user search dialog box.

4. Enter the search criteria that identify the users to whom you want to assign a role and then click Search.

5. Select the users you want from the result set by checking the box next to their names.

6. Click Add Selected.

8 IBM Lotus Learning Management System Release 1 Customization Guide

7. Click Continue. The application displays a dialog box from which you can assign roles by clicking Assign Roles. When you click Assign Roles, the application displays a list of the roles defined in the system. Select one or more of these to assign to the selected user(s).

8. Click Save to complete the role assignment(s).

Chapter 3: Controlling access to features 9

10 IBM Lotus Learning Management System Release 1 Customization Guide

Chapter 4 Customizing Help

Every Help topic consists of four files, all of which are editable:

• The file that defines the layout of the graphical bar displayed at the top of every Help window. Student and Course Administrator Help topics have slightly different headers.

• The file that defines the navigation bar containing a list of links at the left of every Help window.

• The file containing the topic content. Topic content files are all named <prefix>_<topic>_b.html, where <prefix> identifies the topic as being a Student or Course Administrator Help topic. By convention, the prefix sh_ identifies a Student Help topic; ch_ identifies a Course Administrator Help topic.

• The map file that defines the frameset in which the header, navigation bar, and topic content are displayed. Map files are all named <prefix>_<topic>.html where <prefix>_<topic> matches the <prefix>_<topic> of the corresponding content file.

All of these files reside in a single directory on a server. Student and Course Administrator Help topics reside in separate subdirectories. Depending on how you configure the application after installation, there may be copies of the Help system on multiple servers. Users of the Offline Learning Client download (Student) Help to their workstations. If Help is installed on multiple servers, you should make any changes on all of them. Users of the Offline Learning Client should be advised to download a new version incorporating your changes.

Users access topics in the Help system in either of two ways:

• From the Student or Course Administrator Help table of contents or index.

• By clicking the ? icon on the current page. When the user clicks this icon, the application

displays the Help topic relevant to that page. This is known as context-sensitive Help.

The following sections look at the construction of a sample of a Help topic and describe the various ways in which you can customize a Help window’s display attributes and content, redirect context-sensitive Help, and add a new Help topic to the system.

The Anatomy of a Help topic

The following example shows the component parts of the Help topic for the Student Preferences dialog box.

The map file sh_preferences.html looks like this:

<html>

<head>

<title>IBM Lotus Learning Management System Student Help</title>

</head>

Chapter 4: Customizing Help 11

</frameset>

</html>

The file sh_help_header_h.html defines the layout of the graphical bar that appears at the top of all Student interface Help topics, sh_help_navigation_l.html defines the navigation bar that appears on the left of each Student help topic containing links to other parts of the Help system, and sh_preferences_b.html is the file containing the topic text in this example.

You could edit sh_preferences.html the content of the title attribute in the frame name tags, adjust the dimensions of the frameset and its components, and specify different links for the header, navigation bar, and topic. The title attribute is included for the benefit of users using textto-speech software.

The header file sh_help_header_h.html looks like this:

<head>

<title>Help Header</title>

<!—

if (navigator.appName.indexOf('Netscape') > -1) {

document.write('<LINK HREF="ns_style.css" REL="styleSheet" TYPE="text/css">');

} else {

document.write('<LINK HREF="ie_style.css" REL="styleSheet" TYPE="text/css">');

}

// -->

</SCRIPT>

</head>

<html>

<td class="logo-text" nowrap valign="middle"> Learning Management System Student Help<br><img src="transparent.gif" width="137" height="1" alt="" border="0"></td>

12 IBM Lotus Learning Management System Release 1 Customization Guide

</tr>

</table>

</body>

</html>

The <SCRIPT>…</SCRIPT> block tests for which browser you’re using and points to the appropriate Cascading Style Sheet (CSS) in the Help directory to manage display attributes, such as font and background color, of the Help header and navigation bar. You can change these display attributes by editing ns_style.css or ie_style.css (or both) or by pointing to a different Cascading Style Sheet of your own devising. If you edit the CSS files rather than point to one of your own, these changes will ripple through the whole Student Help system.

You can alter the ALT tag text, and change the banner textLearning Management System Student Help. You can edit, replace, or remove the lvc-help-*.gif files. You can change the banner graphic in either of two ways:

• Edit or replace the file lvc-helpmosaic.gif.

• Edit ns_style.css or ie_style.css (or both), replacing the background-image URL with one

that locates the banner graphic you want:

.mosaic-bg {

background-image: url(lvc-helpmosaic.gif);

background-repeat: repeat-x;

You can use transparent.gif to adjust the spacing of elements in the header.

The file that defines the navigation bar, sh_help_navigation_l.html, looks like this:

<html>

<head>

<title>Help Navigation</title>

<!--

if (navigator.appName.indexOf('Netscape') > -1) {

document.write('<LINK HREF="ns_style.css" REL="styleSheet" TYPE="text/css">');

} else {

document.write('<LINK HREF="ie_style.css" REL="styleSheet" TYPE="text/css">');

Chapter 4: Customizing Help 13

}

// -->

</SCRIPT>

</head>

<tr>

<td width="100%"><a href="sh_contents.html" class="navtext" target="_top">Contents</a></td>

</tr>

<tr>

<td><a href="sh_index.html" class="nav-text" target="_top">Index</a></td>

</tr>

<tr>

<td><a href="sh_glossary.html" class="nav-text" target="_top">Glossary</a></td>

</tr>

<tr>

<td><a href="sh_faq.html" class="nav-text" target="_top">Frequently Asked Questions</a></td>

</tr>

14 IBM Lotus Learning Management System Release 1 Customization Guide

<tr>

<td><a href="http://doc.notes.net/cct/LearningSpace.nsf/LSCore?OpenForm" class="nav-text" target="_ ">Feedback on Help?</a></td>

</tr>

</table>

</body>

</html>

You can change the navigation bar’s display attributes by editing ns_style.css or ie_style.css (or both) or by pointing to a different Cascading Style Sheet of your own devising. (Again, if you edit the CSS files rather than point to one of your own, these changes will ripple through the user interface.)

You can alter the contents of the navigation bar by rearranging, adding, or removing rows in the <table>…</table> block.

Finally, the content file sh_preferences_b.html looks like this:

<HTML>

<HEAD>

<TITLE>Changing your display preferences</TITLE>

</HEAD>

<H2>Changing display preferences</H2>

<p>By clicking Preferences in the Navigation bar, you can see and change your personal display preferences. To close the window without changing your preferences, click Cancel.</P>

…

</body>

</html>

Chapter 4: Customizing Help 15

You can ignore or remove the <META> tags at the beginning of the file. These are used in generating the Index. Otherwise, you can edit this file as you would any other standard HTML file.

Editing an existing Help topic

Open the _b.html, edit it, and save your work.

Replacing a context-sensitive Help topic

You can replace a context-sensitive Help topic by linking to a different topic, which can be either another topic in the existing Help system or one that you write yourself. The mechanism for replacing the link varies, depending on whether the associated JSP is a pop-up or not. For a popup, edit the jsp:param name “helpPage” attribute in the JSP. For example, if you want to change the link for context-sensitive Help for the Preferences dialog box, change sh_preferences.html to some other HTML file in the directory identified by the relative path student/ in preferences.jsp:

<%--

preference.jsp

Description:

Allows users to modify their preferences

--%>

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

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

<jsp:include page="popupHeader.jsp" flush="true">

<jsp:param name="messageKey" value="toolbar.preferences"/>

<jsp:param name="header" value="toolbar.preferences"/>

<jsp:param name="helpPage" value="student/sh_preferences.html"/>

</jsp:include>

<lms:form action="/prefSubmit.do">

<%--

For JSPs that aren’t pop-ups, edit the <helpPage> attribute of the description of the JSP in Navigation.xml. For example, you might replace the context-sensitive help topic for the Student Home page, sh_usinghome.html with some other HTML file in the directory identified by the relative path student/:

- <module>

<name>studenthome</name>

<target>/studentHome.do</target>

<content>studentHomeWelcome.jsp</content>

<label>navigationTab.studentHome</label>

<title>navigationTab.studentHome</title>

<permissions>Home_Module</permissions> <helpPage>student/sh_usinghome.html</helpPage>

16 IBM Lotus Learning Management System Release 1 Customization Guide

Note: You can replace a Help file with one in another directory by specifying the appropriate relative path and file name. For example, you might change the helpPage parameter in preferences.jsp to

<jsp:param name="helpPage" value="courseadmin/ch_mypreferences.html"/>

or, assuming that you had created and populated a myhelp directory at the same level as the student and course administrator Help directories, you might change the <helpPage> tag in the student home entry in Navigation.xml to

<helpPage>/myhelp/welcome.html</helpPage>

or the like.

Adding your own Help topic

You can add your own Help topics to the system and create Index entries and links in the Table of Contents for them. The following procedure assumes that you want to add a topic to the Student Help system. The procedure for adding a topic to the Administrator Help system is essentially the same, the only significant differences being the prefix to the file namesch_ instead of sh_ and the subdirectory in which you store the files.

1. Create a map file like the one described above in “Anatomy of a Help topic” (sh_preferences.html). For example, you might create a file named sh_my_topic.html to which the corresponding content file will be named sh_my_topic_b.html:

<html>

<head>

<title>IBM Lotus Learning Management System Student Help</title>

</head>

</frameset>

</html>

2. Create the content file (sh_my_topic_b.html). Since you’ll need to enter Index entries by hand if you want the topic to be available through the Index, you don’t need to include <META> tags:

<HTML>

<HEAD>

Chapter 4: Customizing Help 17

<TITLE>Your title goes here (for example, My Topic)</TITLE>

</HEAD>

<H2>Your title goes here (for example, My Topic)</H2>

<p>Your topic text goes here.</P>

</BODY>

</HTML>

3. If you want to link to this topic from the Table of Contents, open sh_contents_b.html, enter the appropriate text, and save your work. For example:

<A HREF="sh_notifications.html" target="_top">Notifications</A><br>

<A HREF="sh_my_topic.html" target="_top">My topic</A><br>

<A HREF="sh_enrolled.html" target="_top">Enrolled courses</A><br>

4. If you want to link to this topic from the Index, open sh_index_b.html in the .war file, enter the appropriate text, and save your work. For example:

<dt>ToolTips <dd><a href="sh_preferences.html" target="_top" title="Link to topic">Changing your display preferences</a>

<dt>topic details <dd><a href="sh_coursedetails.html" target="_top" title="Link to topic">Course and activity details </a>

<dt>topic, my <dd><a href="sh_my_topic.html" target="_top" title="Link to topic">My topic</a>

18 IBM Lotus Learning Management System Release 1 Customization Guide

Chapter 5 Customizing JavaServer Pages

You can customize the Learning Management System application by customizing its JavaServer Pages. This chapter contains the following information:

Overview

• LMS JSP tag libraries

• The Anatomy of a JSP

Making global changes

• Applying customization sets

• Changing application style

• Updating page text

• Replacing graphics

Changing individual JSPs

• Changing a JSP’s style

• Altering a JSP’s functionality

Overview

The architecture of the Learning Management System application is based on Struts 1.1, beta 2, which is part of The Jakarta Project, sponsored by Apache Software Foundation. The Struts architecture helps to separate logic from presentation in a JavaServer Page application using the MVC (Model-View-Controller) design pattern. In this design pattern, the Model component represents the business logic of the application, the View represents the display mechanism, and the Controller passes control from the request to the model and from the model to the view.

In the Learning Management System application, a user request triggers the initialization of a controller servlet that parses a configuration file. The configuration file, named Struts-config.xml, maps the request to the appropriate action class to handle it. Action classes on the Learning Management System server have a .do extension and those on the Delivery server have a .ds extension. Once the handler performs the action, it calls a form class to structure the result. It also determines which JavaServer Page the response should be forwarded to for display in the browser. The Struts-config.xml file contains action mappings that map the forwards returned by the actions to specific JavaServer Pages. The Struts-config.xml file contains both global forwards and one or more additional forwards for specific actions. You can find documentation defining the Struts architecture at http://jakarta.apache.org/Struts/

The view component of the MVC model is handled by JavaServer Pages in the Learning Management System. The JavaServer Pages reside on each server hosting the application. JavaServer Pages (JSPs) are pages comprised of standard HTML, JavaScript, Java scriptlets, and JSP tags. JSP tags are similar to HTML tags; both define display characteristics for elements on a page. However, JSP tags differ in that they also serve as references to Java code. Each JSP tag triggers the execution of a piece of Java code written and stored elsewhere in the application. The attributes of a JSP tag serve as the parameters to pass to the Java class.

A JSP is served to a browser client from the server of the hosting application. It works like this: when a JSP-based application is deployed, the server pre-compiles the JavaServer Pages into a servlet, which executes any code triggered by the JSP tags on the page and dynamically generates the response page content. These pre-compiled JSPs are stored in the server’s file directory. When

Chapter 5: Customizing JavaServer Pages 19

a user makes a request or performs an action, the server handles the action, and then retrieves the appropriate JSP to display the response in HTML. You can find documentation defining the JSP

1.2 specification, on which the LMS JSPs are based, at http://java.sun.com/products/jsp/.

The servers in the LMS application display their responses to requests differently. The Learning Management System server displays its responses using either a popup JSP or a template JSP that provides additional formatting to the page, called the adminTemplate.jsp. The Delivery server displays its responses using a framing JSP called delivery.jsp. To step through the source code for these pages, see “The Anatomy of a JSP.”

LMS JSP tag libraries

The servers that host the LMS application support custom JSP tags from multiple JSP tag libraries. Each library has a tag library descriptor (TLD) file, which is an XML-formatted file that defines the attributes of the JSP tags in the library and the Java classes to call when each tag is encountered on a page.

The tag library descriptor files in the IBM Lotus LMS are named as follows:

IBM Lotus Learning Management System tag library descriptor files Tag Library Name Purpose:

lms.tld Executes the basic functionality of the LMS application. Used by the JSPs in

every component of the LMS application. Struts-bean.tld Calls JavaBeans™ from a JSP. Based on the Struts architecture. Struts-html.tld Defines the basic HTML content of a JSP, such as button and checkbox elements.

Based on the Struts architecture. Struts-logic.tld Incorporates common programmatic logic into a JSP. Based on the Struts

architecture.

The Delivery and Offline Learning Client servers contain the following TLD files in addition to those listed above:

Tag Library Name Purpose:

chat.tld Executes the functionality used in conducting a live chat from within the

application.

delivery.tld Defines the functionality specific to the delivery and offline servers, such as the

activity and course tools.

delivery-js.tld Customizes the frames used to format the delivery and offline client

applications.

These TLD files are stored in the following directory:

[serverName]>WEB-INF>tld

where [serverName] is one of the following directory names:

• “LMM”: Represents the Learning Management System server

• “DS”: Represents the Delivery server

• “DUC”: Represents the Offline Learning Client server

The anatomy of a TLD file

The tag library descriptor (TLD) file is a text file in XML format that defines the JSP tags used in an application. In this section we will look at one such JSP tag. The url tag is a tag that references a Uniform Resource Locator (URL). It belongs to the lms tag library and is defined in the lms.tld file.

This section illustrates how to:

• Reference a tag in a JSP

• Define a tag in the TLD file

20 IBM Lotus Learning Management System Release 1 Customization Guide

Referencing the url tag in a JSP

The following code is excerpted from the catalogManageCurriculumEntryManage.jsp:

function openUserSearchPopup()

{

var href = "<lms:url>/searchUserPopup.do?formName=<%= formName %></lms:url>";

<lms:window href="href" title="UserSearch" width="600" height="700" scrollbars="true" resizable="true" />

}

</script>

When called, the openUserSearchPopup() script opens a popup window and populates it with the searchUserPopup JSP, which displays a standard search form. The searchUser.jsp file, which is included in the searchUserPopup.jsp file contains the following code:

String formName = request.getParameter("formName");

This code sets a new variable called formName equal to the formName variable passed to it from the lms:url tag. Essentially, the lms:url tag is formatting the text in its body as a valid URL, which is passed to the lms:window tag as the content of its href attribute. The lms:window tag does the work of opening a window and displaying the content referenced by the URL.

Defining the url tag in the TLD file

The following XML-formatted text is an excerpt from the lms.tld:

<tag>

<tagclass>com.lotus.elearn.taglib.UrlTag</tagclass>

<name>encodeURL</name>

<required>false</required>

<rtexprvalue>false</rtexprvalue>

</attribute>

<name>useCustomDsPath</name>

<required>false</required>

</attribute>

<name>useCustomLmmPath</name>

<required>false</required>

</attribute>

<required>false</required>

Chapter 5: Customizing JavaServer Pages 21

</attribute>

</tag>

The tag name is defined in the <name> tag:

The next line identifies the location of the Java source code to execute when this url tag is encountered on a JSP:

<tagclass>com.lotus.elearn.taglib.UrlTag</tagclass>

The source code for all of the Java classes specified in the LMS custom TLD files is stored in the following directory:

[serverName]>WEB-INF>classes>com>lotus>elearn>taglib

The url tag source is no exception; the UrlTag.java file is stored in the lmm>WEBINF>classes>com>lotus>elearn>taglib directory.

The bodycontent tag provides information on the content of the body of the JSP tag and is intended for use by page composition tools:

“Jsp” indicates that the body of the tag contains nested JSP syntax. Page composition tools know how to handle Jsp syntax. Some JSP tags have bodycontent tags that contain “Empty.” This specifies that no text can display in this tag when it is executed.

Once the properties of the JSP tag are defined, any attributes associated with the JSP tag are then defined before the closing JSP tag (</tag>) is reached. Each attribute has a name tag and two more informational tags, the “required” and “rtexpvalue” tags. If the required tag is set to “true,” any time you include the JSP tag in a page, you must provide a value for this attribute for the tag to be evaluated properly. The rtexpvalue tag indicates whether or not the value of the attribute may be dynamically calculated at request time, as opposed to being a static value determined at translation time.

The first attribute of the url tag, named encodeURL, is not required and its value cannot be dynamically calculated at request time. This attribute takes a Boolean value that indicates whether or not to call the HTTPResponse.encodeURL() method to encode the URL included in the body of the tag into a browser-readable format. This attribute should be set to true for URLs that target other pages in the application, since it encodes the URL with the session ID, if necessary. (For browser clients that do not accept cookies, this is the only way to pass the session ID and maintain the session state information for the application.)

<name>encodeURL</name>

<required>false</required>

<rtexprvalue>false</rtexprvalue>

</attribute>

The next two attributes, the useCustomDsPath and useCustomLmmPath attributes, are also not required. The values of these attributes can be dynamically calculated at request time. These attributes take Boolean values and indicate whether or not the customization set paths provided for the Delivery(DS directory) and Learning Management System (LMM directory) servers should be used in locating the URL included in the body of the tag. The default value for these tags is “true,” which indicates to apply the customization set path to the supplied URL, if a customization set exists. Setting these to false forces the retrieval of a resource from a specific URL regardless of whether customization sets are in effect for an application.

22 IBM Lotus Learning Management System Release 1 Customization Guide

<name>useCustomDsPath</name>

<required>false</required>

</attribute>

<name>useCustomLmmPath</name>

<required>false</required>

</attribute>

The fourth attribute, the id attribute, is not required and can be dynamically calculated at request time. By including this attribute in a url tag and setting it equal to a string, you are creating a PageContext variable named with the string you supply.

<required>false</required>

</attribute>

The end of the url tag is indicated by a closing tag tag that follows the last attribute’s closing tag:

</tag>

The Anatomy of a JSP

This section defines the JSPs that structure the display of the content of the Learning Management System and Delivery servers.

Learning Management System server

The JSPs that reside on the Learning Management System server are displayed in two ways. They either display as popups, which have little or no header and navigation information, or they display in the adminContentPage section of the adminTemplate.jsp, which functions as a template that formats the page content. Stepping through the source code of the adminTemplate JSP illustrates how to perform standard JSP tasks, such as:

• Defining a page as a JSP

• Including tag library descriptor files

• Referencing Struts tags and standard JSP actions

• Including JavaScript source code

Looking at the adminTemplate.jsp source code also illustrates how the following tasks are handled by the Learning Management System server in particular:

• Localizing page text

• Determining the user’s browser type and language preference

• Including the JSPs that comprise the main template

You can find the full source code for the adminTemplate.jsp file in the WEBINF>classes>resources>lmm directory. The code below is an excerpt from this file.

Defining a page as a JSP

Chapter 5: Customizing JavaServer Pages 23

The first block of executable code is a page directive that applies to the entire page and specifies the language of the page as Java and sets the MIME type and character encoding to use for the response:

<%@ page language="java" contentType="text/html;charset=UTF-8" %>

Including tag library descriptor files

The next block of code is made up of taglib directives. These identify the names of the tag libraries associated with the page. They also identify the prefixes to use before tags from each library.

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

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

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

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

Referencing Struts tags

The next line of code is an html tag from the Struts-html tag library. The “html” before the colon is the prefix representing the Struts-html tag library and the “html” after the colon represents the tag in that library named html:

<html:html locale="true">

The value “true” in the locale attribute indicates to set the current locale for the user if needed. This prompts the servlet to retrieve the locale from the requesting browser. The value returned determines which language-version resources to use for the rest of the session.

Localizing page content

The next group of tags makes up the head HTML tag. The META tag defines the character set to use for the HTTP response message header. In the next line, we see another JSP tag at work. The message tag in the lms tag library is programmed to retrieve the resource key specified in the key attribute from the .properties resource file and display it on the page. Since the content of the application.title resource key in the ApplicationResource.properties file for the LMM application contains the text, “IBM Lotus Learning Management System,” this is text that displays as the title on the adminTemplate page. See “Updating page text.”

<head>

Including standard JSP actions

The next line of code is a standard JSP action called the getProperty tag. This tag and any others that have a jsp prefix are standard JSP actions and are available for use in all JSPs. See the JavaServer Pages 1.2 Specification downloadable from http://www.jcp.org/aboutJava/communityprocess/final/jsr053/for more details. The getProperty tag initializes a JavaBean, which is a reusable Java component, and retrieves a property from it.

Determining the user’s browser type and language preference

The property being requested, the “styleSheetLink” property, contains the name of the appropriate CSS file to apply to the page based on the type of browser that is submitting the user request.

<jsp:getProperty name="BrowserSniffer" property="styleSheetLink"/>

24 IBM Lotus Learning Management System Release 1 Customization Guide

+ 65 hidden pages

IBM R1 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual