Chapter 8   Customizing the Desktop End-User Online Help


This chapter provides information on customizing the Sun™ ONE Portal Server Desktop online help.

This chapter contains the following sections:

• Overview of the Desktop End-User Online Help

• Location of the Desktop End-User Online Help HTML files

• Modifying the Desktop End-User Online Help HTML files

Overview of the Desktop End-User Online Help

---

The Desktop end-user online help is a collection of HTML files that is referenced in the display profile. Each provider, including the various container providers, has a display profile entry for a corresponding help file. In the display profile, each provider definition has the default value for the help file. If a channel that uses the provider has a different help file, the helpURL property can be defined in the channel definition also, overriding the provider's value.

The display profile entries for the online help are defined in the provider properties. The entries define the string name, helpURL, and its value.

For example, Code Example 8-1 shows the display profile definition for UserInfoProvider and the helpURL property for the user information online help file.

---

Code Example 8-1    HelpURL Property in Display Profile Definition

<Provider name="UserInfoProvider" class="com.sun.portal.providers.userinfo.UserInfoProvider">

<Properties>

<String name="title" value="*** Userinfo Provider ***"/>

<String name="description" value="*** DESCRIPTION ***"/>

<String name="refreshTime" value="0" advanced="true"/>

<Boolean name="isEditable" value="true" advanced="true"/>

<String name="editType" value="edit_subset" advanced="true"/>

<String name="width" value="thin" advanced="true"/>

<String name="helpURL" value="desktop/userinfo.htm"             advanced="true"/>

<String name="fontFace1" value="Sans-serif"/>

<String name="productName" value="Sun ONE Portal Server"/>

The value of the helpURL property can be either a relative path or an absolute path. The location in Code Example 8-1 is relative to the Desktop static content root.

The static content root is the install directory of static content. By default the static content root is:

/opt/SUNWps/web-apps/https-psserver/portal

The relative path will be generated as:

static_content_root/doc_root/locale/helpURL_value

The doc root is defined in the display profile also. For example, if the doc root is docs, and the user's locale is en_US, with the helpURL value, the final value for the help location will be:

/opt/SUNWps/web-apps/https-psserver/portal/docs/en_US/desktop/userinfo.htm

Code Example 8-2 shows an example of an absolute URL that defines a help file location.

---

Code Example 8-2    Format For Using an Absolute URL to Define the Location of an Online Help File

<String name="helpURL" value="http://sesta.com/docs/desktop/userinfo.htm"/>

Location of the Desktop End-User Online Help HTML files

---

The default location of the Desktop end-user online help files for the sample Desktop is:

/opt/SUNWps/web-apps/https-server/portal/docs/locale/desktop

Table 8-1 provides a list of help files included with the sample portal. In the table, the first column lists the names of the help files. The second column contains a brief description of the help file.

Table 8-1    Sample Desktop Help Files  

File Name	Description
bkmark.htm	Describes the bookmark channel.
home.htm	Describes the Home link on the Desktop.
mlchck.htm	Describes the mail check channel.
search.htm	Describes the search channel.
urlscrpr.htm	Describes the sample URL scraper channel.
content.htm	Describes the Content link on the Desktop.
SunONE.jpg	Displays the Sun One logo graphic image.
myapps.htm	Describes the My Applications channel.
sections.htm	Section help file (describes frames-based Desktop sections).
usechann.htm	Provides an overview of using the Desktop channels.
ix.htm	Provides an index for the online help.
notes.htm	Describes the notes channel.
tabs.htm	Provides an overview of using a tabbed Desktop interface.
usedesk.htm	Provides an overview of using the Desktop.
fdesktop.htm	Provides an overview of using the Desktop (for frames-based Desktop).
jspchann.htm	Describes the JavaServer Pages™ channel.
userinfo.htm	Describes the user information channel.
glossary.htm	Provides a glossary for the online help.
layout.htm	Describes the Layout link on the Desktop.
options.htm	Describes the Options link on the Desktop.
theme.htm	Describes the Theme link on the Desktop.
webchann.htm	Describes the simple web service channel.
help.htm	Describes the Help link on the Desktop.
logout.htm	Describes the Logout link on the Desktop.
rsschann.htm	Describes the RSS channel.
topics.htm	Provides a table of contents for the online help.
xmlchann.htm	Describes the XML channel.
login.htm	Describes the membership login channel.

Modifying the Desktop End-User Online Help HTML files

---

You can customize the end-user online help by editing the existing HTML online help files or by creating new HTML files.

To Edit An Existing Help File

You can edit an existing help file to customize the content to meet specific requirements of your organization. For example, you can remove or change the SunONE.jpg image or meta text that is currently displayed on the sample help files, or replace the help file completely with a file of the same name.

This method of modifying the online help files is useful if you use the sample providers that are shipped with the Sun ONE Portal Server product.

For example, if you use the UserInfoProvider that ships with the Sun ONE Portal Server product, the display profile for that provider already defines the helpURL value as desktop/userinfo.htm. By editing the help file userinfo.htm, no changes to the display profile are necessary.

• See "Location of the Desktop End-User Online Help HTML files" for the online help file names and descriptions, and where they are installed on your system.

To Create a New Help File

You can create a new help file by creating a new HTML file. This method of customizing the online help is useful if, for example, you add a new provider to the Desktop. When you create a new help file, you must modify the display profile to contain the new helpURL value. You can either manually edit the display profile or use the iPlanet Directory Server Access Management Edition admin console.

To create a new online help file and to define the helpURL value manually, do the following:

1. Create an HTML file for the provider you want to document.

2. Place your file in the appropriate directory.

   You can place your custom help files under the web server document root, in the directory specifed as root by the display profile:

   /opt/SUNWam/public_html/docs/locale/desktop

   Or, you can deploy them in a custom web application archive. See the web server documentation for information on how to deploy a web application archive.

3. Define the helpURL value for that file in the display profile.

   To define the helpURL value for a new online help file, use the format described in the section "Overview of the Desktop End-User Online Help."

4. Use the dpadmin command to load the display profile into LDAP.

5. Verify that the new help file is displayed correctly.

To create a new online help file and to define the helpURL value in the iPlanet Directory Server Access Management Edition admin console, do the following:

1. Create an HTML file for the provider you want to document.

2. Place your file in the appropriate directory.

   You can place your custom help files under the web server document root, in the directory specifed as root by the display profile:

   /opt/SUNWam/public_html/docs/locale/desktop

   Or, you can deploy them in a custom web application archive. See the web server documentation for information on how to deploy a web application archive.

3. Login to the iPlanet Directory Server Access Management Edition admin console as the administrator.

4. Choose the Organization.

5. Choose Services.

6. Choose the arrow next to Desktop.

7. Choose the Edit Channel link.

   The display profile properties are shown.

8. In the channels area, choose Edit for the channel you want to edit.

9. Enter the helpURL Value.

10. Choose Save.

11. Verify that the new help file is displayed correctly.