Chapter 2   Customizing Display Profiles


This chapter contains the following sections:

• Accessing Display Profiles

• Using the Display Profile Editor

• XML Tags

Accessing Display Profiles

---

When you start iPlanet Market Maker, the main page displayed is called the portal page. This page is dynamically generated based on a description of the available content. This description of this content is called a display profile.

The display profile is defined in an XML document. iPlanet Market Maker features a display profile editor that lets you edit and customize the XML tags that define the display profile.

This chapter provides an example for interpreting and customizing a display profile. The type of display profile editing described is typically done by the market maker or company administrator.

Using the Display Profile Editor

---

The display profile editor is the tool you use to make changes in the display profile associated with a particular LDAP node. To start the display profile editor, type DPEdit on the command line. After you complete the login procedure, you can access and edit the XML tags that define the display profile.

Figure 2-1 shows the basic structure of the XML tags that define the display profile.

Figure 2-1    Display Profile Structure

XML Tags

---

This section contains a list of the XML tags you can access and edit to customize the display of the iPlanet Market Maker portal.

<DISPLAYPROFILE>
The DISAPLAYPROFILE tag is the root element that encloses the entire document. It contains any number of the following two tags in any order.

• <PAGE>

• <CLASSNAME>

This tag has no attributes.

<PAGE>
The PAGE tag encloses the information relevant to a top-level or portal page. It can contain any number of <TOP> tags.

This tag has a required NAME attribute.

The NAME attribute specifies the name of page that applies to the <PAGE> tag, such as the file name of a portal JSP.

<CLASSNAME>
The CLASSNAME tag maps a symbolic name to a Java class so that you can change class names specified elsewhere in a document in one place. This tag is optional. You can also specify classes directly. If you use this tag, it must appear before, or at a higher inheritance level than, other tags that use it. This tag has no content.

This tag has the following two attributes.

ATTRIBUTE	DEFINITION
CLASS	Name of the Java class (sub-class of DisplayElement).
NAME	Name to refer to the class in symbolic references.

<TOP>
The TOP tag describes a top-level element, usually a container, that may be instanciated on the <PAGE> in which it is contained. The <TOP> element has subelements that fully describe the container: its settings, available list, and member list. With this information, the portal module can call the relevant classes and display the container and its content.

In the display profile you describe what can be displayed. In the JSP you use this description to tell the engine how to render it. The name provided in this tag is the name to use in the JSP when you create the container as a Java object. This name is the link between the portal JSP and the DisplayProfile.

For example:

In the display profile there is a <PAGE> element called mypage.jsp that has a <TOP> element named myTabularLayoutContainer.

If you want to use this container, use a portal page named mypage.jsp that contains the following code:

<%

elt = new TabularDisplay("myTabularLayoutContainer");

elt.doDisplay();

%>

to specify that a TabularDisplay is to be shown in a particular part of the JSP, and that it corresponds to the <TOP> tag named myTabularLayoutContainer in the display profile.

This tag may optionally start with an <AVAIL> tag followed by a <MEMBERS> tag. Following these two tags can be a <SETTINGS> tag.

The <AVAIL> and <MEMBERS> tags represent the content of a container, and are usually present. These tags should be missing only if this <TOP> tag is a single content item, or if it is cloned. If the CLONE attribute was specified, the <AVAIL> and <MEMBERS> tags can still be present, and are aggregated onto the cloned settings.

The <TOP> tag has the following attributes.

ATTRIBUTE	DEFINITION
NAME (required)	Links the item to a particular page element.
CLONE (optional)	Indicates that the content for this tag is to be copied from a previous place in the document. This attribute allows content to be moved to different places within the containment hierarchy without being duplicated. Currently, it is specified by surfacing an internal key mechanism. The syntax is [<page>]<elt>, where <page> is the JSP name, and <elt> is component names starting with the "top" name, connected by "_c_".
CLASS (optional)	Documents the class instanciated in the JSP. For informational purposes only.

<Avail>
The Avail tag defines the list of available content for a container, which can be content items or further containers. This tag can contain any number of <AVAILITEM> or <REMOVAL> tags.

The <AVAIL> tag has an optional "REPLACE" attribute you can set to 1 or 0.

If 1, the list replaces any inherited list form an earlier document, rather than augmenting it. This attribute is not usually used. If it appears, it effectively defeats any "CLONE" mechanism specified on the tag containing it, because the list is cloned, then thrown away. The default is 0.

<MEMBERS>
Describes the current content for a container and always appears in with an <AVAIL> tag, whose list members it references by name. This tag can contain any number of <CONTENT>, <CONTAINER>, or <REMOVAL> tags. These tags reference items by name in the parallel <AVAIL> list.

The <MEMBERS> tag has an optional "REPLACE" attribute you can set to 1 or 0. If 1, the list replaces any inherited list form an earlier document, rather than augmenting it. This attribute is not usually used. If it appears, it effectively defeats any "CLONE" mechanism specified on the tag containing it, because the list is cloned, then thrown away.

<SETTINGS>
Contains arbitrary name-value pairs to be used by an enclosing <TOP>, <CONTENT> or <CONTAINER> tag. Represents item-specific attributes with particular types, either single elements or arrays. This tag can contain any number of <STRING>, <BOOLEAN>, <INTEGER>, <OBJECT> or <ARRAY> tags.

This tag has no attributes.

<AVAILITEM>
This tag defines an available content item within a container.

This tag appears inside <AVAIL> and represents a member of a list present for <TOP> and <CONTAINER>. It links a particular name to a class. <CODEMAP> is an alternate class to map an <AVAILITEM> based on an action tag. The <AVAILITEM> tag can also contain a <SETTINGS> tag that specifies the initial settings to be propagated to the parallel item in the <MEMBERS> list when the user adds a channel.

This tag has the following attributes.

ATTRIBUTE	DEFINITION
NAME	Required attribute that specifies the name of the item as referred to in the <MEMBERS> lists parallel to the <AVAIL> list that contains this item.
CLASS	Required attribute that specifies the actual DisplayElement sub-class corresponding to this item or the symbolic name specified by an earlier <CLASSNAME> tag.
DESCRIPTION	A string that defines the user variable description for this item, such as dialogs.
DESCRIPTION_KEY	An integer used to look it up in the "DisplayProfile" properties file so the string may be internationalized (translated to a different language).
DEFCODE	Integer "action code" (operation) initially applied to the element.
DEFINDEX	Integer index associated with the operation.
MULTIPLE	Can be 0 or 1. If 1, indicates that multiple instances of this item are allowed. The default is 0.
CONTENTMASK	A string specifying permissions required to see this content take the form of a comma separated list of "|" separated names. A user gets a list of permissions at login time, which is compared against this list. One of the "|" separated names from each comma separated component must be possessed to see the item. Could be generalized to an arbitrary boolean expression.

<REMOVAL>
Specifies the removal of an inherited named item from an <AVAIL> or <MEMBERS> list. This tag has the following attributes.

NAME	Specifies the item to remove in an <AVAIL> list.
ITEMNAME	Specifies the item to remove in a <MEMBERS> list.
SUFFIX (optional)	Distinguishes multiple members constructed from the same <AVAILITEM>.

<CONTAINER>
A member of a <MEMBERS> tag that describes a content item that is a container aggregating more items. Its attributes link it to the appropriate <AVAILITEM> in the <AVAIL> list parallel to the <MEMBERS> list it resides in, as well as providing information about its manipulation within the container.

This tag must contain one <AVAIL> tag, followed by one <MEMBERS> tag. It can optionally contain a <SETTINGS> tag after the <MEMBERS> tag.

This tag has the following attributes.

ATTRIBUTE	DEFINITION
ITEMNAME (required)	Links it by name to an <AVAILITEM>. If the <AVAILITEM> allows multiple copies, there should also be a "SUFFIX" attribute that distinguishes the multiple members constructed from the same <AVAILITEM>.
IDNUMBER (optional)	Integer attribute currently used only for tabbed displays. It allows JSP code constructing very dynamic tab bars to identify tabs programmatically. It is generally an application-defined integer identifier for the member.
CLONE	See the "CLONE" attribute description under <TOP>.
SUFFIX	Specifies the member to remove.
PERMANENT (optional)	Set to 0 or 1. If 1, indicates that the item is not intended to be removable by the user.
COORD (optional, but usually	A comma-separated list of integers used by the container to arrange its members. The number of required coordinates and their interpretation depends on the container. For instance, in a tabular arrangement, this specifies the column/row.

<CONTENT>
This tag defines a member that is content, not a further container.

This tag can contain a single <SETTINGS> tag. Its attributes are identical to the attributes for the <CONTAINER> tag.

<STRING>, <BOOLEAN>, <INTEGER>, <OBJECT>
Name data items contained in a <SETTING> tag.

The "NAME" attribute must be present, unless the tag is the member of an <ARRAY> tag. The "VALUE" attribute containing a string appropriate for the type must also be present, except that for <STRING>, it can be replaced with "VALUE_KEY" that provides an integer key allowing the value to be read from the DisplayProfile properties file, so that it can be internationalized (translated to a different language). Note that the appropriate type of <BOOLEAN> is "true" of "false".

For <OBJECT>, the value is understood to be a serialized object. You usually do not need to edit or enter <OBJECT> tags.

These <OBJECT> tags are usually generated at run-time by your program if it makes use of the display profile mechanism to store some settings for an individual user.

<ARRAY>
Allows for array-valued members of the <SETTINGS> tag. This tag can contains further <STRING>, <BOOLEAN>, <INTEGER>, <OBJECT> and <ARRAY> tags. The "NAME" attributes on these tags are ignored because they are accessed as members of the whole named array.

This tag has a "NAME" attribute that must be present unless this array is, in turn, a member of another <ARRAY>.

Inheriting and Merging of Display Profiles

---

The display profile that applies to a user is inherited depending on the LDAP node for that user. iPlanet Market Maker has the following types of nodes.

• Market Maker

• Buying club (also called Group)

• Company

• Role

• User

The market maker node is the root display profile. The buying club nodes inherit the display profile defined by the market maker node. The company node inherits the display profiles from the buying club node and the market maker node, and so on down the node hierarchy. See Figure 2-2.

Figure 2-2    LDAP Node Hierarchy

At run-time, the display profiles are merged depending on the user node. All the nodes show in Figure 2-2 are merged, in the specified order, to determine the user's run-time display profile.

Creating a New Display Profile

---

The DPEdit editor lets you access a particular LDAP node in isolation from the other nodes. Suppose, for example, that as a company administrator you wanted to change the company logo that appears in the portal page after a user logs in to iPlanet Market Maker. Do the following steps.

1. Log in to the display profile editor and open a new file.

2. Specify the Company node.

3. Create a new display profile that replaces the existing iPlanet Market Maker logo.

Because the Company display profile is inherited from the Market Maker display profile, the first step to change company logo is to understand how that logo is specified in the Market Maker display profile. The Market Maker must provide access to this display profile information. For example, Figure 2-3 shows where the company logo is defined in the default iPlanet Market Maker portal page displayed after a user logs in.

Figure 2-3    Location of Company Logo Definition

To specify a different company logo for your Company node, add the following code in the display profile editor to replace the market-maker defined tags shown in Figure 2-3.

<DISPLAYPROFILE>

<PAGE NAME="imm.jsp">

<TOP NAME="comlogosmall">

<AVAIL />

<MEMBERS REPLACE="true">

<CONTENT ITEMNAME="ComLogoSmall">

<SETTINGS>

<STRING NAME="FileRoot" VALUE="imm" />

<STRING NAME="ContentFile" VALUE="logo.html" />

<BOOLEAN NAME="NoMenuBar" VALUE="true" />

</SETTINGS>

</CONTENT>

</MEMBERS>

<SETTINGS />

</TOP>

</PAGE>

</DISPLAYPROFILE>

In this example, the contents defined in the logo.html file replace the contents defined in the immlogosmall.html file in the default market maker display profile.

Interpreting Tabbed Displays

---

The NAME attribute of the third <TOP> tag ("top") Figure 2-4 defines with a tabbed display (TabbedDisplay) in the imm.jsp file. In a tabbed display, the COORD attribute determines the order in which the tabs are displayed. The container for a tabbed display can provide a tab bar, or allow the JSP to construct a tab bar as is done in imm.jsp. If the JSP manages the display of the tab bar, the COORD attribute might be irrelevant depending on the logic in the JSP.

It is possible to define content filtered by user privileges, which is why the tabbed display shows different content for different users. This is also why the item corresponding to the login page is shown only when you are not yet logged in.

Under the third <TOP> tag shown in Figure 2-4, the first <CONTENT> tag defines a tabular layout container for the channels displayed in the "anonymous" portal page, which is the page displayed when you first start Market Maker and the role of the user is not known. This <CONTENT> tag is a typical container in which you add channels.

Because only one item is available to be displayed in this example, the JSP does not construct a tab bar.

Figure 2-4    "Anonymous" Portal Page

The second of these <CONTENT> tags in Figure 2-5 defines the channels displayed in the "MyMarketPlace" portal page, which is the page displayed when you log in to Market Maker. Regardless of your role, the "My Marketplace" tab is the default active tab. In this example, the JSP creates the tab bar.

Figure 2-5    "MyMarketplace" Portal Page

Adding a Channel to a Portal Page

---

Suppose that as a market maker you wanted to add a channel to the "Anonymous" portal page. The default iPlanet Market Maker display profile for this page is shown in Figure 2-6.

Figure 2-6    Container for the "Anonymous" Portal Page

Under the <CONTENT> tag for the "Anonymous" container, you use the display profile editor to add a new channel as shown in the following example.

<CONTENT ITEMNAME="Anonymous">

<AVAIL>

<AVAILITEM NAME="Developer"

CLASS="com.iplanet.ecommerce.vortex.display.FileContent" DESCRIPTION="My Documents" DEFCODE="-1" DEFINDEX="0" />

</AVAIL>

<MEMBERS>

<CONTENT ITEMNAME="MyDocuments" COORD="0,1,0">

<SETTINGS>

<STRING NAME="FileRoot" VALUE="MyDir" />

<STRING NAME="ContentFile" VALUE="doc/customization.html" />

</SETTINGS>

</CONTENT>

This code adds a channel called "My Documents" in the "Anonymous" page. The contents of this channel are defined by the customization.html file.

About the Display Profile Loader

---

Display profiles are XML documents that define the contents of the iPlanet Market Maker portal. Marketmaker administrators can use the display profile editor to access and edit display profiles. The display profile loader is a tool for marketmaker administrator to load the modified community display profile information in the LDAP server and Oracle database. You use the display profile loader at installation time and whenever you want to change the portal display.

The community module defines a hierarchy of entities for the marketmaker, companies, and users. You can modify display profiles at the level of each of these entities to customize the iPlanet Market Maker portal display. You use the display profile loader to load these XML documents.

Using the Display Profile Loader

To run the display profile loader, use the following command.

java com.iplanet.ecommerce.vortex.tools.dpimport.LoadDisplayProfile -load | -unload config_file.xml

The inputs to this command line are described in the following table.

DISPLAY PROFILE LOADER INPUT	DESCRIPTION
-load	Uses the entries to load the display profiles.
-unload	Uses the entries GUID to delete any display profile associated with them.
-confiv_file.xml	Name of the XML configuration file that the display profile editor uses to control the load process. This file format is described below.

The load configuration file consists of a set of <LOADITEM> elements. A <LOADITEM> element specifies the community <NODE>, identified by its GUID, for which the config_file.xml file is loaded and a <FILE> to load.

The display profile loader does the following operations.

Goes to LDAP and sets the hasdisplayprofile attribute to true for this GUID.

Goes to Oracle and puts the file in a CLOB field in the CMN_CONFIG_PROFILE table, with the GUID as a key.

After the tool has run, the display profiles specified in the XML files are available for use in the iPlanet Market Maker software.

<?xml version="1.0"?>

<DPLOADCONFIG>

<WORKDIR PATH="">

</WORKDIR>

<LOADITEM>

<NODE NAME="vortex" GUID="5b6abf:de3f060a01:-7fff">

</NODE>

<FILE NAME="demodp.xml">

</FILE>

</LOADITEM>

</DPLOADCONFIG>

CONFIGURATION FILE XML TAG NAME	DESCRIPTION
WORKDIR	Working directory path.
LOADITEM	Has two mandatory elements: NODE and FILE. NODE describes a community node, with an optional NAME used in the output and a mandatory GUID.
FILE	Specifies a file to upload. The attribute NAME is the name of the file.