Part III Display Profile

• Chapter 13, Introduction to Display Profile

• Chapter 14, Display Profile Document

• Chapter 15, Display Profile Objects

• Chapter 16, Document Priorities

• Chapter 17, Merge Semantics

• Chapter 18, Display Profile Properties: Overview

• Chapter 19, Display Profile Properties: Global Properties

• Chapter 20, Display Profile Properties: Container Provider Properties

• Chapter 21, Display Profile Properties: Leaf Building-Block Provider Properties

• Chapter 22, Display Profile Properties: Service Provider Properties

• Chapter 23, Display Profile Properties: Content Provider Properties

• Chapter 24, Display Profile Common Properties for Leaf Providers

• Chapter 25, Display Profile Channel Properties

Chapter 13 Introduction to Display Profile

This chapter contains the following sections:

• What is Display Profile?

• Administering the Display Profile

What is Display Profile?

The display profile is a series of XML documents describing container management and properties for providers and channels. The display profile creates the display configuration for the Desktop by defining the following items in the XML document:

Provider definition

Specifies the name and the Java class for the provider. A provider is a template used to generate content, which is displayed in the channel. See Provider Object for more information.

Channel definition

Specifies the run-time configuration of an instance of the provider class. A channel is a unit of content, usually (but not necessarily) arranged in rows and columns. You can also have channels of channels, that is, container channels. See Channel Object for more information.

The container channel properties include the display definition about how to display the contained channels in the container, including: the layout of the container (thin-wide, wide-thin, or thin-wide-thin); a list of the contained channels; the position of the channel (the row and column number); and the window state of the contained channels (minimized or detached).

Provider and channel property definitions

Specify the values for provider and channel properties. Properties defined in a provider usually specify default values for the channels that are derived from the provider. The display configurations for the channels include properties such as the title, description, channel width, and so on. The properties defined in the channel usually specify the specific value for that channel that is different from the default value. See Property object for more information.

If a property is not defined in the channel, then the default value for the property as defined in the provider is used. If a property is defined in the channel, then the value for the property defined in the provider is ignored.

The display profile does not actually define the overall layout or organization of what users see on their Desktops. The display profile exists only to provide property values for channels. However, the display profile does indirectly control some aspects of channel presentation, such as column layout for a table container or how the table container draws channels in a table.

Administering the Display Profile

You can use the Portal Server Console and psadmin to administer the Portal Desktop Service data and the Display Profile. In the Portal Server console, you can upload, download, and remove the display profile from a specific dn. You can edit the desktop service attributes. You can modify channels and containers properties. You can also create, edit, and remove channels in the containers. The psadmin provides commands, which allow you to list, add, remove, modify, and merge display profiles. For more information, see the Sun Java System Portal Server 7.1 Administration Guide.

Chapter 14 Display Profile Document

This chapter contains the following sections:

• Document Structure

• How are the Display Profile XML Documents Stored?

• Types of Display Profile Documents

Document Structure

This chapter describes the overall structure of the display profile documents. The underlying data format for a display profile document is XML.

The display profile format is intended to define the Desktop’s display configuration by defining provider and channel objects and their properties. Thus, a display profile is made up of some number of display profile objects. The display profile objects map directly to the XML tag that defines them. For example, the <Channel name=> XML tag defines a channel object.

In general, the document structure of a display profile document resembles the following:

<DisplayProfile>
    <Properties>...global properties...</Properties>
    <Channels>...channel definitions...</Channels>
    <Providers>...provider definitions...</Providers>
</DisplayProfile>

The hierarchical structuring of the display profile document does not define the visual layering of channel on the portal Desktop. The display profile exists only to provide property values for channels on the Desktop.

The display profile contains definitions that enable you to construct the Desktop. These definitions include providers, channels, containers, and properties. Some of these definitions create the Desktop containers—the frames, tables, and tabs that arrange the content of the Desktop—and others create channels for the Desktop via the respective providers. A display profile provider definition is a template for building channels based on that provider.

The following sections describe the display profile objects in detail.

How are the Display Profile XML Documents Stored?

Display profile documents are stored in their entirety as a single attribute in the Sun Java System Sun Java System Access Manager software services layer. Potentially, the Portal Server software could store a display profile document for a user’s organization or sub-organization, each role the user belongs to, and the user. That is, for the different LDAP nodes (base DN, org DN, role DNs, and uid DN), you can store a display profile document. There is also a global display profile document.

The user’s display profile is a series of XML documents describing container management and properties for channels. (One display profile document is equivalent to one XML document.) The user’s display profile document set is made up from the non-empty documents stored at the user’s organization, various sub-organizations, any roles, and the user LDAP nodes. This display profile document set is “merged” at runtime to form a single configuration for the user’s Desktop.

To change display profile property values, the providers use the provider APIs (PAPI) to get and set the values. When the channel values are set to the display profile, the PAPI internal implementation uses the Sun Java System Access Manager SDK to set the display profile document in the Sun Java System Access Manager software Desktop service attribute.

Though possible, you should not edit the display profile using the Sun Java System Access Manager SDK.

Types of Display Profile Documents

This section explains the different types of display profile documents and how to use the Sun Java System Portal Server console to administer them.

Global Display Profile Document

Defines display profile elements that are inherited by all users on the system, regardless of the organization or role to which they belong. (Although currently not enforced, you might also want to use the display profile XML document to define the common providers that will be used by everyone.)

Dynamic Display Profile Document

Describes container management and properties for channels. This display profile is not ”used’ to generate a user’s Desktop at runtime, but becomes the default for each newly created organization and role. By default, the dynamic display profile document is blank. To use the dynamic display profile, you need to first populate it.

Organization, Suborganization, or Role Display Profile

Shows the display profile for the selected organization, suborganization, or role. When you create a new organization, suborganization, or role, you create a template for this entity. When you create the template for the Desktop service, the initial display profile is set to the dynamic display profile document as mentioned above. Thus, if the dynamic display profile is blank, nothing is filled in.

Most likely, you use this display profile document to customize container management and channel properties to fit the needs of different organizations and roles.

Chapter 15 Display Profile Objects

This chapter contains the following sections:

• Introduction

• Object Lookup

Introduction

There are three basic types of objects in the display profile: channels, providers, and properties. Every object in the display profile is associated with a DN. The channels, providers, and properties display profile objects are used to group other display profile objects. These grouping objects are loosely referred to as “bags.” These bags add more structure to the display profile XML documents.

Channel Object

A channel object represents a single display element. The objects contained by a channel object can be thought of as properties for the channel. The channel definition includes a symbolic reference to the provider. You only need to include channel-specific properties when the provider defaults are not appropriate.

Example 15–1 Example Channel Object XML Syntax

<Channel name="SampleXML" provider="XMLProvider">
    <Properties>
        <String name="refreshTime" value="600"/>
        <String name="title" value="XML Test Channel"/>
        <String name="description" value="This is a test of the
			XML Provider system"/>
        <String name="url" value="file:///var/opt/SUNWportal/portals
			/<portal_id>/desktop/
			default/SampleXML/getQuotes.xml"/>
        <String name="xslFileName" value="/var/opt/SUNWportal/
			portals/<portal_id>/desktop/
			default/SampleXML/html_stockquote.xsl"/>
    </Properties>
</Channel>

Container Object

A container object is identical to a channel object, except that it primarily generates its content by aggregating the content of other (its child) channels. A container object allows for available and selected channel lists and can contain leaf channel definitions. A leaf channel is typically aggregated on a page with other channels and generates its own content. A container channel primarily generates content by aggregating the content of one or more leaf channels. Both leaf and container providers are building blocks in that they can be extended (through their public interfaces) to create new or custom providers.

Example 15–2 Example Container Object XML Syntax

<Container name="JSPTableContainer" provider="JSPTableContainerProvider">
    <Properties>
        <String name="title" value="JSP Based Table Container Channel"/>
        <String name="contentPage" value="toptable.jsp"/>
        <String name="description" value="This is a test for front table containers"/>
        <String name="Desktop-fontFace1" value="Sans-serif"/>
        <Collection name="categories">
            <String value="Personal Channels"/>
            <String value="Sample Channels"/>
            <String value="News Channels"/>
        </Collection>
        ...
    </Properties>

        <Channels> ...leaf definitions go here...</Channels>

</Container>

Provider Object

The provider is a programmatic entity responsible for fetching and displaying content in a channel. The XML tag for defining a provider object is <Provider name=“providerName” class=“providerClass”>.

A provider object is a pointer to the display profile provider definition. The provider is a contract between ProviderContext and channel instance (provider object).

The display profile stores provider definitions that are available to the channel and containers to implement their content generation behavior. The display profile provider definition contains the information necessary for a client of the display profile to construct the provider object, namely, the Java class name. The class that implements the provider’s behavior is defined in the provider attribute. Channels use the name attribute values to refer to the provider.

The provider definition sets default property values for all channels that point to this provider. Channel-specific properties are only necessary when the provider defaults are not appropriate. The provider display profile object should contain default values for all properties that are used in the provider Java object. For example, if the provider Java code contains:

getStringProperty("color")

the provider display profile object should have a default value for color.

Example 15–3 Example Provider Object XML Syntax

<Provider name="XMLProvider" class="com.sun.portal.providers.xml.XMLProvider">
    <Properties>
        <String name="title" value="*** XML Provider ***"/>
        <String name="description" value="*** DESCRIPTION ***"/>
        <String name="width" value="thick"/>
        <String name=”color” value=”blue”/>
        <String name="refreshTime" value="0" advanced="true"/>
        <Boolean name="isEditable" value="false" advanced="true"/>
        <String name="helpURL" value="desktop/xmlchann.htm" advanced="true"/>
        <String name="fontFace1" value="Sans-serif"/>
        <String name="productName" value="Sun Java System Portal Server"/>
        <String name="url" value="file:///var/opt/SUNWportal/portals/<portal_id>/
			desktop/default/xml/getQuotes.xml"/>
        <String name="xslFileName" value="html_stockquote.xsl"/>
        <Integer name="timeout" value="100"/>
        <String name="inputEncoding" value="iso-8859-1"/>
        <String name="urlScraperRulesetID" value="default_ruleset"/>
        <Boolean name="cookiesToForwardAll" value="true"/>
        <Collection name="cookiesToForwardList">
        </Collection>
    </Properties>
</Provider>

Property object

A property value that can be specified for a channel. Individual properties are grouped within the <Properties></Properties> tags inside a channel definition.

Like display profile objects are grouped within their appropriate XML tag pairs. That is, providers are grouped within <Providers></Providers> tags, channels within <Channels></Channels> tags, properties within <Properties></Properties> tags.

Because you can have multiple display profile documents defined at different LDAP nodes, at runtime, the system merges these multiple display profile documents to deliver a particular Desktop to the user. This process of merging display profile documents affects the final display profile object values.

Object Lookup

At runtime, the system never asks for properties directly from a provider. The request always goes to a channel. If a Java provider object requests a property, it searches the display profile in the following order until it finds the property, or until it reaches the top of the containment hierarchy:

To Perform Object Lookup:

1. Channel’s properties

2. Channel’s provider’s properties

3. Channel’s parent’s properties

4. Channel’s parent’s provider’s properties

5. Channel’s parent’s properties (and so on)

6. The global properties bag defined in the display profile root definition

   Therefore, when a channel asks for the names of its properties, it gets the set of the union of all the above.

   Properties that exist in a provider object are intended to have the semantics of default values for the channel. For example, for a provider XML that defines property title, all channels that are derived from provider XML inherit the title property. If the channel wants to override this property, it can set the value within its own properties.

Chapter 16 Document Priorities

This chapter contains the following sections:

• Overview

• Examples

• Summary

Overview

At runtime, when a user logs in, the system determines the set of documents that makes up the user’s display profile document set. The Desktop internal implementation of the display profile (the part that interprets the display profile) determines this set by looking at all of the LDAP nodes that the user belongs to. This can be the organization DN (dc=sesta.com), suborganizations, role DNs (cn=Role1,dc=sesta.com), and uid (uid=user,ou=People,cn=Role1,dc=sesta.com), as well as the global display profile. The display profile documents from each of these LDAP nodes and global display profile are then read (if it exists there), and all of the documents are put into a set. The system sorts the set according to the document priorities. A lower number represents a lower priority. For example, a 1 is a lower priority than a 2. The documents are then sorted from lower number to higher number. See Process of Merging for more information on this process.

The user level document (uid=amAdmin,ou=People,...) is a special case referred to as the base document. Think of the base document as a priority equal to infinity. Thus, it is always the highest number (and hence highest priority). All of the mergers are associated with the base document in sorted order, and the priority setting on a user document is always the highest. The priority attribute used in the <DisplayProfile> tag takes the special keyword user to indicate that the current display profile is the user level display profile.

When a merge occurs, it starts at the lowest priority document (lowest number) and proceeds in increasing priority number, until it arrives at the user (base) document.

Thus, the implication of display profile document priorities is that what really matters is the priority number. For example, an organization level document can have a higher priority than a role level document, but it does not have to. It depends on how you need to prioritize these documents for your site.

Specify the display profile document priority in the XML file with the <DisplayProfile priority= syntax> tag. You can change the priority by directly editing the display profile XML by using the Sun Java System Portal Server console or by using the psadmin command to load the display profile.

Do not assign the same priority to two display profile documents. Doing so causes the Desktop to not appear properly. However, the product does not check for duplicate document priorities.

Examples

The examples provided below shows the display profile documents for organization and a bill.

Example 1

This example uses two display profiles, one for the organization example and one for the uid bill. When Bill logs in (uid=bill) to the Desktop, the bookmark channel titled “Bill’s Bookmarks” is displayed with the following three bookmarks (in that order):

• ACME

• Amazon

• EBay

Example 16–1 Display Profile Document for the Organization (dc=acme.com)

<DisplayProfile version="1.0" priority="10">
...
<Channel name="Bookmark" provider="BookmarkProvider" merge="fuse">
    <Properties>
        <String name="title" value="My Bookmarks" merge="replace"
 			lock="false" propagate="true"/>
        <String name="refreshTime" value="600" merge="replace"
			lock="false" propagate="true"/>
        <Collection name="targets" merge="fuse" lock="false"
			propagate="true">
            <String value="ACME home page|http://www.acme.com"
				 merge="replace"
				lock="false" propagate="true"/>
        </Collection>
    </Properties>
</Channel>
...
</DisplayProfile>

Display Profile Document for the uid=Bill,ou=people,o=acme.com

<DisplayProfile version="1.0" priority="10"> ... <Channel name="Bookmark"
provider="BookmarkProvider" merge="fuse"> <Properties> <String name="title"
value="Bill’s Bookmarks" merge="replace" lock="false" propagate="true"/>
<Collection name="targets" merge="fuse" lock="false" propagate="true"> 
<String value="Amazon|http://www.amazon.com" merge="replace" lock="false" 
propagate="true"/> <String value="EBay|http://www.ebay.com" merge="replace"
lock="false" propagate="true"/> </Collection> </Properties> </Channel> ... 
</DisplayProfile>

Example 2

This example uses three display profiles, the global display profile, the display profile for the organization acme, and the display profile for the role hradmin. When the user who is assigned to the hradmin role logs in to the Desktop, the JSPTableContainer appears with the following channels:

• SampleSimpleWebService

Example 16–2 Global Display Profile Document

<DisplayProfile version="1.0" priority="0">
...
<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties>
        ...
    </Properties>
    <Available>
        ...
    </Available>
    <Selected merge="fuse" lock="false">
        <Reference value="UserInfo"/>
    </Selected>
    <Channels/>
</Container>
...
</DisplayProfile>

Display Profile Document for the Organization (dc=acme.com)

<DisplayProfile version="1.0" priority="0"> ...
 <Container name="JSPTableContainer"
provider="JSPTableContainerProvider" merge="fuse">
<Properties> ... </Properties>
<Available> ... </Available> <Selected merge="fuse"
lock="false"> <Reference value="UserInfo"/>
<Reference value="Notes"/> </Selected> <Channels/>
</Container> ... </DisplayProfile>

Display Profile Document for the hradmin Role

<DisplayProfile version="1.0" priority="0">
...
<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties>
        ...
    </Properties>
    <Available>
        ...
    </Available>
    <Selected merge="fuse" lock="true">
        
        <Reference value="SampleSimpleWebService"/>
    </Selected>
    <Channels/>
</Container>
...
</DisplayProfile>

Summary

A display profile document has a low or high priority depending on whether you consider the merge order or the ability to lock as the defining factor.

Without considering locking, the lower numbered display profile document has a lower priority. The lower numbered display profile document gets merged first so the value of a higher priority document overrides the value of a lower priority document. In this sense, the lower numbered document has a lower priority.

However, the lower numbered display profile document can also lock an object so it cannot be affected by a higher numbered document. In this sense, the lower numbered document has a higher priority.

Chapter 17 Merge Semantics

This chapter contains the following sections

• Introduction

• Process of Merging

• Merge Locking

Introduction

The display profile is composed of a hierarchy of XML documents. The software can store a display profile document for the user, each role the user belongs to, and the user’s organization or suborganization. At runtime, the system merges these multiple display profile documents to deliver a particular portal desktop to the user. This process of merging display profile documents affects the final display profile by potentially changing channel, provider, and property definitions.

The display profile data format contains syntax that defines how these documents are combined. This definition is commonly known as merge semantics.

Merge semantics control how attributes are combined as display profile documents from different LDAP nodes (base DN, DN, and role DNs) which are merged to form a single representation (that is, Desktop). Merge semantics assume an ordering to display profile documents. The Sun Java System Portal Server 7.1 software imposes an additional ordering on Sun Java System Access Manager software roles to simulate a hierarchical structure.

The set of display profile documents for a user consists of: the documents that exist at the user’s LDAP organization and suborganization nodes; the documents that exist at each of the user’s role nodes; and the document that exists at the user’s entry node. Documents do not need to be defined at each of these nodes, but there must be at least one document defined at a node. The set of documents is sorted according to a priority value that the display profile document defines. See Display Profile Document Priorities for more information.

You can visualize the process of document merging as laying one display profile document on top of another. A merge happens where like named channels, providers, and properties fall on top of one another. Merging is based on the name of the display profile object, not the XML structure defined in the display profile document. Like named channels can exist in different containers within the containment hierarchy in the display profile to be merged.

For example, Figure 18–1 shows a sample DIT with each level having its own display profile document. At the top of the tree is the global display profile. Next is the base DN, dc=sesta,dc=com. It has a two role DNs, training and manager. The tree ends at the uid DN, user1. Each node in the DIT has its own display profile document. The resultant display profile document is produced through a merge of all the display profile documents, based on their priorities. This merge result is presented to the user at login. Merge semantics control how display profile documents are combined. These semantics include replace, remove, and fuse. Display profile objects can also be locked. During the merge, a higher priority document can lock a display profile object to prevent a lower priority document from altering it.

Figure 17–1 Example of Merge Process

Process of Merging

When a user logs in to the Portal Server 7.1 Desktop, and after authentication takes place, the system determines the user’s display profile by:

To Determine the User Display Profile:

1. Locating all the display profile documents for that user by searching through the global display profile, and LDAP organization, suborganization, role, and user nodes that the user belongs to.

2. Placing the retrieved display profile documents in a temporary area, which can be visualized as a bag.

3. Sorting the display profile documents in the bag based on priority, starting at the lowest priority. (The node at which the document was retrieved does not influence the priority sorting. Also, the user display profile document always has the highest priority.)

4. Taking the documents out of the bag, lowest priority first, then placing the next higher level priority document over this document, and applying merge and lock semantics.

5. Continuing Process of Merging until all the documents have been taken out of the bag so that the system returns a value to the user that is a merge of the objects found in the documents.

Types of Merge

This section explains the types of merge available to combine the display profile documents.

Overview

Display profile uses the following three types of merges to determine how to combine display profile documents:

replace

All the display profile objects defined in the higher priority document completely override the ones defined at the lower one. If the object does not exist in the lower priority document, it is added to the merge result (the object replaces the value in the merge results).

remove

The named object is removed from the merge up to this point (the object is removed from the merge results). It no longer exists in the display profile (but it can be re-introduced by another document to be merged). It can be redefined by a higher priority document.

fuse

The object from the lower priority document is combined with one from the higher priority document (the object is merged with the value in the merge results).

The exact meaning of each merge type depends on the display profile object they are applied to.

For channels and providers, fuse has special meaning. The channels themselves are not actually fused together. Rather, fuse indicates that the channel’s or provider’s properties should be combined. The replace semantic replaces the entire channel or provider, including all properties. The remove semantic removes the entire channel or provider from the merge up to that point.

The display profile <DisplayProfile> root node can also have merge semantics. The replace semantic means that all the DP objects defined in the higher priority document completely override the ones defined at the lower one. All merges up to that point are negated and the higher priority document is used as the new base for merging. The remove semantic indicates that all merge results up to the point of this document are to be discarded. The merge begins with the next display profile document found in the sorted set. As with channels and providers, the fuse semantic means that the contained objects (channels and providers) should be combined.

Atomic display profile properties (those that cannot contain other properties) cannot use the fuse semantic. This includes the String, Integer, Boolean, and Reference properties.

The set of properties for a channel consists of the channel’s properties plus the channel’s provider’s properties plus the channel’s parent’s properties, and so on. You can think of this total set of properties as the channel’s single document properties. An implication of document merging is that the total set of properties for a document consists of the set union of the channel’s single document properties for all documents in the user’s merge set.

Examples

This section provides examples for merge types such as remove, replace, and fuse.

Remove Example

This example uses the merge type remove to modify a container’s selected channel list.

The following example code shows how the merge sets of all users can consist of an organizational level document that contains the following display profile fragment.

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="UnixTipoftheDay"/>
    </Selected>
</Container>

The “unix tip of the day” describes ways to use UNIX. It is likely that users that belong to the admin role would not find this channel helpful. To remove this channel from everyone with the admin role, define the TemplateTableContainer channel in the admin role document as follows:

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
        <Reference value="UnixTipoftheDay" merge="remove"/>
    </Selected>
</Container>

The preceding sample snippet causes the <Reference value="UnixTipoftheDay"> to be removed from the admin role display profile.

Replace Example

This example uses the merge type replace to remove channel from all users’ display.

The following example shows how for a particular container, a role admin can ignore all of the channels defined in the organization level. The organization definition resembles the following:

<Container name=...>
    ...
    ...
    <Selected>
        <Reference name="X"/>
        <Reference name="Y"/>
        <Reference name="Z"/>
    </Selected>
</Container>

Because the role admin does not want any of the users under that role to have the X, Y, or Z channels, the container is defined as follows:

<Container name=...>
    ...
    ...
    <Selected merge="replace">
        <Reference name="A"/>
        <Reference name="B"/>
        <Reference name="C"/>
    </Selected>
</Container>

The selected list in the role document’s container replaces the selected list in the organization document’s container.

Fuse Example

This example uses the merge type fuse to create role-based channel list.

Use the fuse merge semantic to combine non-atomic display profile objects. These objects include Collection and the available or selected channel lists. Here, fuse indicates that all the properties contained in the non-atomic property should also be merged. Using fuse in this way enables the final non-atomic property presented to the user to be build up from various documents.

The following example display profile documents are for a user who belongs to the admin, employee, and movieFreak roles. The selected channels for the user appear at the end.

Example 17–1 Display Profile for the Admin Role

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
    </Selected>
</Container>

Display Profile for the Employee Role

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Benefits"/>
        <Reference value="EmployeeNews"/>
    </Selected>
</Container>

Display Profile for the movieFreak Role

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="NewMoviesReleases"/>
        <Reference value="MovieShowTimes"/>
    </Selected>
</Container>

The resultant list of selected channels for the user is as follows, with the available channel list ordered in the same way that the merging was applied, from lower to higher priority:

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
        <Reference value="Benefits"/>
        <Reference value="EmployeeNews"/>
        <Reference value="NewMoviesReleases"/>
        <Reference value="MovieShowTimes"/>
    </Selected>
</Container>

Merge Locking

Any display profile object that is able to be merged can also be locked. When an object is locked, it cannot be affected by merge semantics in higher priority documents. This enables low-priority documents to prevent a high-priority document from using the merge semantics to change particular aspects of the display profile.

Examples

Example 1

This example demonstrates how to use the merge lock feature to force property value for all users. The example shows how to ensure that for a particular organization, all users see the “employee news” channel. The users cannot remove this channel from their display. At the organization level document, the container channel’s selected list is defined as follows:

<Selected merge="fuse">
    ...
    <Reference value="EmployeeNews" lock="true"/>
    ...
</Selected>

Example 2

This example demonstrates how to use the merge lock feature to forcibly remove channel from all users’ display. The example shows how to force the “online games” channel to be removed. In this scenario, users have added this channel to the selected channels list in their user document, so simply removing it from the organization level document’s selected channel’s list will not work. Instead, the employee and organization lists will be merged together resulting in the “online games” channel being present. To forcibly remove the channel from all users under the organization, the selected channels list is defined as follows:

<Selected merge="fuse">
    ...
    <Reference value="OnlineGames" merge="remove" lock="true"/>
    ...
</Selected>

Here, the remove semantic removes the channel from merged result, and lock prevents lower priority documents from merging the value back in.

Chapter 18 Display Profile Properties: Overview

This chapter contains the following sections:

• Introduction

• Display Profile Properties

• Display Profile Property Types

Introduction

Display profile properties control all aspects of a channel, including:

• Content (available and selected channels)

• Position in the Desktop

• Controls

Display profile properties specify the per-channel configuration in the portal Desktop. Such properties define the visual representation of a channel in so much as the visual representation of the channel is affected by a display profile property.

The sample portal makes use of the following display profile definitions in the PortalServer-base/SUNWportal/samples/desktop directory:

d p-org.xml

Contains the display profile definitions for channels and containers.

d p-providers.xml

Contains the display profile definitions for providers.

d p-anon.xml

Contains the display profile definitions for channels and containers for the authlessanonymous and anonymous users in the default organization.

Display Profile Properties

The display profile properties are contained in a properties “bag.” A bag is simply a grouping mechanism for display profile entities such as channels, providers, and properties. The property itself does not have a properties bag associated with it.

You can associate properties with the following display profile objects:

• <Properties> definition

• <Provider> definition

• <Channel> definition

• <Container> definition

There are four basic categories of properties; they are:

Global

Global properties are accessible to all channels. You set global properties, which are shared by all channels, in the <Properties> </Properties> definition. Themes are an example of a global property. You define the theme data globally to share it among all channels. See “Display Profile Global Properties” on page 46 for more information.

Do not use global properties as defaults for all channels. Instead, use the <Provider> definition, as it sets the property interface used by the provider object that will use the <Provider> definition.

Provider

Provider properties serve two purposes:

• They define a property template or schema, defining the properties that will be used by all channels based on the provider.

• The specific values in the provider serve as default values for channels.

If the property is not defined in channels based on this provider, the default value is used. If the default value is overridden by setting the value within the channel definition, then that value is used. By customizing a provider’s property values, you can customize all channels that the provider generates.

Channel

Channel properties are available to the channel in which that properties are associated with. By customizing an individual channel’s properties, you customize that particular channel.

Properties set in the <Provider> definitions are defaults for channels based on that provider. Properties set in <Channel> definitions override the defaults in the provider definition to customize the channel. For example, URLScaperProvider defines a url property. A default does not make sense here, thus a channel would naturally override this value.

Container

Containers are simply channels that generate the majority of their content by executing other channels (or containers). Many of the properties defined for containers pertain to how to gather and arrange content from other channels. For example, properties set in the <Container> definition can describe how to display the contained channels in the container, including: the layout of the container (thin-wide, wide-thin, or thin-wide-thin), a list of the contained channels, the position of the channel (the row and column number), and the window state of the contained channels (maximized, minimized, or detached).

Lower priority display profile documents can overwrite properties of higher priority display profile documents using merge locking. That is, the lock stops the merge on a particular property or value. See Chapter 17, Merge Semantics for a complete discussion of the semantics of the display profile merging.

Display Profile Property Types

This section lists the property types for provider definitions. These can be used with leaf and container providers. This three column table lists the property types in the first column, a brief description in the second column, and an example in the third.

Chapter 19 Display Profile Properties: Global Properties

There are no global properties defined in the base Desktop. Global properties are added via the sample portal installation. So, if you did not install the sample portal, by default, you do not have any global properties defined in the base Desktop.

Use global properties to assign properties that apply to all channels. For example, this chapter shows (a snippet of) the global properties defined in the dp-org.xml display profile file that is part of the sample portal. You assign the global properties inside the <Properties> </Properties> definition by using tags such as <Collection> </Collection>, <String> </String>, <Integer> </Integer>, and so on.

Example for Global Properties Sample

Example 19–1 Global Properties Sample in the Display Profile dp-org.xml File

<DisplayProfile version="1.0" priority="10">
    <Properties>

        <Collection name="GlobalThemes" propagate="false">
            <Collection name="SunTheme">
                ...        
            </Collection>
        </Collection>
        <Collection name="UserTheme">
            ...
        </Collection>
        <String name="docroot" value=”/docs/”/>
        <ConditionalProperties condition="locale">
            <String name="en_US" value="English (United States)"/>
        </ConditionalProperties>
        <String name="helpURL" value="en/desktop/usedesk.htm" advanced="true"/>
        <Collection name="userDefinedChannels" propagate="false"/>
    </Properties>

The list of all global attributes available with the default installation of the sample portal and their description are:

GlobalThemes

Defines the global themes for the Desktop. Themes are mainly focused on channel decoration like background color, channel border color, border width, and font face. Custom themes give the end user the ability to change the look and feel of the Desktop beyond the preset themes.

Global themes can be added in the display profile and changed by users in their Desktops. See “Customizing the Global Themes” on page 259 for information on adding global themes.

UserTheme

Defines the theme that shows up in the user’s Desktop. The value must be one of the collection values defined in GlobalThemes. In dp-org.xml file, the value can be either theme1 or theme2. When users customize their Desktops, the value UserTheme will change.

docroot

Specifies the online help doc root relative to the installed portal/static location. See the Javadocs for more information on the getHelp() method in the ProviderContext API.

helpURL

Specifies a default help file that is used by all containers. If helpURL is specified in the container provider definition, then that one is used.

userDefinedChannels

Specifies the page to allow users to Create New Channel.

Chapter 20 Display Profile Properties: Container Provider Properties

This chapter contains the following sections:

• Introduction

• Available and Selected List

• Common Properties for Table Container

• Common Properties for Tab Container

• Other Container Properties

Introduction

This chapter contains information on the display profile definitions and the properties of the building-block and internally used container providers that ship with Sun Java System Portal Server software.

Container providers enable you to aggregate channels inside the Desktop. The container building-block providers are building blocks in a sense since you can also customize them or use them differently by changing the container properties. They include:

• JSPTableContainerProvider - JSPTableContainerProvider is an extension of JSPProvider. This JSP table provider displays the content channels in a table.

• JSPTabContainerProvider - JSPTabContainerProvider is an extension of JSPProvider. This tab container provider displays a channel that is made up of a number of tabs with titles on them. By default, the JSPTabContainerProvider uses JSPTableContainer to lay out content for each tab. However, it can use JSPTableContainer, JSPSingleContainer, or JSPTabContainer to layout content for each tab.

• JSPSingleContainerProvider - JSPSingleContainerProvider is an extension of the JSP container provider. The single container provider displays one channel in it.

See the Javadocs for more information on these containers.

Available and Selected List

All containers must define a list of available and selected channels. The presence of these is what mainly distinguishes a container from a channel.

Conceptually, the available list defines the set of channels that can be displayed in the container. The selected list defines those that are actually displayed in the container.

To take a specific example, consider the table container. Table containers use the available channel list to store channels that the user may add to their Desktop. The selected list is used to store the set of channels that are visible in their portal page. Typically, the selected channels are a subset of the available channels.

Containers are not required to make use of the available and selected channel lists in the display profile. A container may manage its contained channels in other implementation dependent ways. However, it is recommended that containers use the display profile available and selected channel lists in order to standardize how they are administrated.

The list of required container properties and their description are:

Available

Defines a list of all available channels for this container. The <Available> and </Available> tags define the list, and the <Reference value=> tag defines the list items. For example:

<Available> <Reference value="App"/> <Reference value="Bookmark"/> </Available>

Selected

Defines a list of selected channels for this container. Only selected channels are displayed on the Desktop. The <Selected> and </Selected> tags define the list, and the <Reference value=> tag defines the list items. For example:

<Selected> <Reference value="App"/> <Reference value="Bookmark"/> </Selected>

Common Properties for Table Container

The following table lists the common properties for table containers and their description.

The <Collection name> </Collection> tags define a list to contain these properties, which are set with the <String> tag.

Common Properties for Tab Container

The list of the properties common to all TabContainerProviders and their description are:

startTab

Tab that is displayed when the user logs in.

makeTabChannel

Container channel name to be used when the user creates a new tab.

makeTabProvider

Container provider to be used as a base provider when the user creates a new tab.

maxTabs

The maximum number of tabs that can be selected on the user’s Desktop.

channelNumber

Used in the naming of newly created tabs by user.

contentChannel

The content channel to be used as the Content page for a user created tab.

TabProperties

The collection property TabProperties creates the new tab. There needs to be a one-to-one mapping between the contents of the TabProperties collection and the available or selected tabs. That is, for every tab specified in the available or selected list, a new collection needs to be defined inside TabProperties collection.

Other Container Properties

The list of properties that are common to all container providers and their description are:

presetThemeChannel

Defines the preset theme channel for the container. The JSP™ defined in the channel displays the Theme->Preset Themes page.

customThemeChannel

Defines the custom theme channel for the container. The JSP defined in the channel displays the Theme-> Custom Theme page.

editContainerName

Defines the edit container channel for this container. When a leaf channel defined in this container is of the type edit_subset, then the edit container channel is used to display a frame for the Edit page for the leaf channel.

Chapter 21 Display Profile Properties: Leaf Building-Block Provider Properties

This chapter describes the display profile definitions and the properties of the leaf building-block providers. Leaf building-block providers generate their own content. They include:

• JSPProvider

• URLScraperProvider

• XMLProvider

JSPProvider

JSPProvider uses JSPs. JSPProvider obtains content from one or more JSP files. A JSP file can be a static document (HTML only) or a standard JSP file with HTML and Java code. A JSP can include other JSP files. However, only the topmost JSP can be configured through the display profile. The topmost JSP files are defined through the contentPage, editPage, and processPage properties. See the Sun Java System Portal Server 7.1 Developer’s Guide for more information on how JSPProvider uses these JSPs. See also Chapter 27, JSPs in the default Directory for the complete list of JSPProvider Communication channels.

If you need to make other customizations, you do so in the JSP files themselves. The list of properties specific to JSPProvider and their description are:

String name="contentPage"

Specifies the JSP that is used to generate the channel content (by using the getContent method).

String name="editPage"

Specifies the JSP that is used to generate the Edit page content (by using the getEdit method).

String name="processPage"

Specifies the JSP that is used to process the results of an Edit page (by using the processEdit method).

Boolean name="showExceptions"

If true, makes JSPProvider show exceptions generated while processing the JSP as the channel output for the getContent and getEdit methods. This can be useful for developing and troubleshooting your portal.

URLScraperProvider

URLScraperProvider takes a URL, opens a connection to the URL, and reads the contents into a buffer. The contents are then sent to the Desktop servlet, which displays it. URLScraperProvider uses the Rewriter to construct the URL information and the content received contains the presentation markup (if applicable).

The list of the properties specific to URLScraperProvider and their description are:

String name="url"

Specifies the URL to be scraped. The default value is /desktop/ipinfo.html.

String name="urlScraperRulesetID"

Specifies the ID of the ruleset to be used by the Rewriter for rewriting content.

Boolean name="cookiesToForwardAll"

Specifies whether to forward cookies.

String name="inputEncoding"

Specifies the input encoding to be used by URLScraperProvider to encode the scraped content.

Collection name="cookiesToForwardList"

Specifies the list of cookies to be forwarded by URLScraperProvider if cookiesToForwardAll is set to false.

Integer name="timeout"

Specifies the timeout for which the provider should wait to fetch content before displaying the timed out message.

The isEditable property for URLScraperProvider cannot be turned on (set to true) as this channel is, by default, not editable. There are no getEdit() and processEdit() methods defined for this provider. If you want edit functionality for URLScraperProvider, define another provider that extends URLScraperProvider. In so doing, you would need to implement the getEdit() and processEdit() methods, and also define the editType property. See the Portal Server Developer’s Guide for more information on extending the URLScraperProvider.

XMLProvider

XMLProvider transforms an XML document into HTML using an XSLT (XML Style Sheet Language) file. You must create the appropriate XSLT file to match the XML document type. XMLProvider is an extension of URLScraperProvider. This provider uses the JAXP 1.1 JAR files that come with Sun Java System Web Server software.

This guide does not discuss XML and XSL technologies. See http://www.w3.org/TR/xslt for more information.

The list of properties specific to XMLProvider and their description are:

String name="url"

Specifies the URL that XMLProvider is to transform.

String name="xslFileName"

Specifies the path to the local file to be used as the XSL style sheet.

The provider code tries to pick up the XSL file either from the XML channel directory (that is, /var/opt/SUNWportal/portals/<portal_id>/desktop/default/SampleXML), or if not specified here, from the XML provider directory (/var/opt/SUNWips/desktop/default/XMLProvider/xml).

String name="urlScraperRulesetID"

Specifies the ID of the ruleset to be used by the Rewriter for rewriting content.

Boolean name="cookiesToForwardAll"

Specifies whether to forward cookies.

String name="inputEncoding"

Specifies the input encoding to be used by XMLProvider to encode the scraped content.

Collection name="cookiesToForwardList"

Specifies the list of cookies to be forwarded by URLScraperProvider if cookiesToForwardAll is set to false.

Integer name="timeout"

Specifies the timeout for which the provider should wait to fetch content before displaying the timed out message.

In the URLScraperProvider, the attributes added to the providerDP are:

<String name="title" value="UrlScraper Channel"/>
<String name="description" value="This is a test for urlscraper"/>
<Boolean name="isEditable" value="false" advanced="true"/>
<String name="editType" value="edit_subset" advanced="true"/>
<Boolean name="enableUBT" value="false" advanced="true"/>
<String name="urlScraperRulesetID" value="default_ruleset"/>
<String name="width" value="thick"/>

<Collection name="cookiesToForwardList">
</Collection>
		<Integer name="timeout" value="100"/>
		<String name="formData" value="" advanced="true" />
		<Boolean name="isHttpAuth" value="false"  advanced="true" />
		<String name="loginUrl" value="" advanced="true" />
		<String name="loginFormData" value="" advanced="true" />
		<String name="uid" value="" advanced="true" />
		<String name="password" value="" advanced="true" />
	</Properties>
</Provider>

Copy the following code, which is the URLScraperProvider property from Portal Server 7.0 to Upgrade install.

<Provider advanced="false" class="com.sun.portal.providers.
urlscraper.URLScraperProvider" container="false"
lock="false" merge="fuse"
name="URLScraperProvider" version="2">
	<Properties advanced="false" lock="false" merge=
	"fuse" name="_properties"
	propagate="true">
		<String advanced="false" lock="false" merge=
		"replace" name="title"
		propagate="true" value="UrlScraper Channel"/>
		<String advanced="false" lock="false" merge="
		replace" name="description"
		propagate="true" value="This is a test for 
		urlscraper"/>
		<Boolean advanced="true" lock="false" merge=
		"replace" name="isEditable"
		propagate="true" value="false"/>
		<Boolean advanced="true" lock="false" merge=
		"replace" name="isTopLevel"
		propagate="true" value="false"/>
		<String advanced="true" lock="false" merge=
		"replace" name="editType"
		propagate="true" value="edit_subset"/>
		<Boolean advanced="true" lock="false" merge=
		"replace" name="enableUBT"
		propagate="true" value="false"/>
		<String advanced="false" lock="false" 
		merge="replace"
		name="urlScraperRulesetID" propagate="true"
		 value="default_ruleset"/>
		<String advanced="false" lock="false" merge=
		"replace" name="width"
		propagate="true" value="thick"/>
		<String advanced="true" lock="false" merge=
		"replace" name="refreshTime"
		propagate="true" value="0"/>
		<String advanced="true" lock="false" merge=
		"replace" name="helpURL"
		propagate="true" value="en/desktop/urlscrpr.htm"/>
		<String advanced="false" lock="false" merge=
		"replace" name="url"
		propagate="true" value=""/>
		<String advanced="false" lock="false" merge=
		"replace" name="fontFace1"
		propagate="true" value="Sans-serif"/>
		<String advanced="false" lock="false" merge=
		"replace" name="productName"
		propagate="true" value="Sun JavaTM System 
		Portal Server 7"/>
		<Boolean advanced="false" lock="false" 
		merge="replace"
		name="cookiesToForwardAll" propagate="true"
		 value="true"/>
		<String advanced="false" lock="false" merge=
		"replace"
		name="inputEncoding" propagate="true" value="UTF-8"/>
		<Collection advanced="false" lock="false" 
		merge="fuse"
		name="cookiesToForwardList" propagate="true"/>
		<Integer advanced="false" lock="false" merge=
		"replace"
		name="timeout" propagate="true" value="100"/>
		<String advanced="true" lock="false" merge=
		"replace"
		name="formData" propagate="true" value=""/>
		<Boolean advanced="true" lock="false" merge=
		"replace"
		name="isHttpAuth" propagate="true" value="false"/>
		<String advanced="true" lock="false" merge=
		"replace" name="loginUrl"
		propagate="true" value=""/>
		<String advanced="true" lock="false" merge=
		"replace"
		name="loginFormData" propagate="true" value=""/>
		<String advanced="true" lock="false" merge=
		"replace" name="uid"
		propagate="true" value=""/>
		<String advanced="true" lock="false" merge=
		"replace" name="password"
		propagate="true" value=""/>
		<ConditionalProperties advanced="false" 
		condition="client" lock="false"
		merge="fuse" propagate="true" value="HTML">
			<ConditionalProperties advanced="false" 
			condition="locale" lock="false"
			merge="fuse" propagate="true" value="en">
				<String advanced="true" lock="false" 
				merge="replace" name="helpURL"
				propagate="true" value="en/desktop/urlscrpr.htm"/>
				<String advanced="false" lock="false"
				 merge="replace" name="url"
				propagate="true" value=""/>
			</ConditionalProperties>
				<String advanced="true" lock="false"
				 merge="replace" name="helpURL"
				propagate="true" value="en/desktop/urlscrpr.htm"/>
				<String advanced="false" lock="false"
				 merge="replace" name="url"
				propagate="true" value=""/>
			</ConditionalProperties>
			<ConditionalProperties advanced="false" 
			condition="locale" lock="false"
			merge="fuse" propagate="true" value="en">
				<String advanced="false" lock="false" 
				merge="replace" name="title"
				propagate="true" value="UrlScraper Channel"/>
				<String advanced="false" lock="false" merge=
				"replace" name="description"
				propagate="true" value="This is a test for
				 urlscraper"/>
			</ConditionalProperties>
		</Properties>
</Provider>

Chapter 22 Display Profile Properties: Service Provider Properties

Service providers provide search service. The Sun Java System Portal Server 7.1 software includes the following service providers:

• SearchProvider

• DiscussionsProvider

• SubscriptionsProvider

SearchProvider

SearchProvider supplies the search function using the Sun Java System Portal Server software Search Engine. SearchProvider is a JSP-based provider. The resultant channel has three interfaces:

Basic search

Enables users to search within the default document database or discussion database. Document and category matches are then displayed.

Advanced search

Enables users to search for documents based on author, title, URL within the default document database or discussion database, discussion, and/or comment. Users can also search on the last-modified date of a document. Advanced search is a more complex user interface, and supports customization. For more information, see Chapter 11, Customizing the Service Providers, in Sun Java System Portal Server 7.1 Developer Sample Guide.

Browse

Enables users to browse the category tree and search within categories.

Search results are displayed based on the categorySearch and viewHits properties. The list of properties specific to SearchProvider and their description are:

String name="contentPage"

Specifies the JSP that is used to generate the channel content (by using the getContent() method).

String name="editPage"

Specifies the JSP that is used to generate the Edit page content (by using the getEdit() method).

String name="processPage"

Specifies the JSP that is used to process the results of an Edit page (by using the processEdit() method).

Boolean name="showExceptions"

If true, makes SearchProvider show exceptions generated while processing the JSP as the channel output for the getContent() and getEdit() methods. This can be useful for developing and troubleshooting your portal, and for debugging the Search provider.

String name="searchServer"

Specifies the Search server’s URL.

Integer name="viewHits"

Specifies the number of hits that should be displayed per page. The maximum desirable number is 25. (The Edit page specifies to choose a number between 1 and 100.) This property is user editable. Edit page displays allowable values as 5, 8, 10, 16.

Boolean name="basicSearchDefault"

If true, specifies that the default search mode should be basic. (Users can set this to advanced if desired.)

String name="defaultMode"

Specifies the default search mode. Allowable values are basic, advanced, or browse.

Boolean name="categorySearch"

Specifies the category search to be displayed by default. If set to false, category matches are not displayed.

DiscussionsProvider

The DiscussionsProvider is JSPProvider based and uses the Desktop themes. It retrieves data from the back end Search service using search taglibs and API. The discussions and comments are stored as separate Resource Descriptors (RDs) in the discussion database. Discussion RDs require special schema. See schema.rdm file in the /var/opt/SUNWportal/searchservers/search1/config/ directory.

Discussions are stored in the discussion database specified in the dbname property in the display profile. Search server host (searchServer property) and database name (dbname property) are advanced properties that can be configured in the display profile.

The list of properties specific to DiscussionsProvider and their description are:

searchServer

Specifies the path to the search server. By default, the value is search1/search.

dbname

Specifies the discussion database where discussions are stored. Any valid database can be specified.

viewHits

Specifies the number of discussions to display on the main discussion page (full view).

defaultDiscussionDisplay

Determines how the comment subtree is displayed. It can be set to flat or threaded to allow the comment subtree to be displayed as flat or threaded.

defaultFilter

Specifies the filter for searching and displaying discussions and this controls display of the subtree. It can be based on ratings such as irrelevant, routine, interesting, important, or must read. By default, its value is irrelevant; so all comments rated irrelevant and above are displayed. The Must read filter will highlight the highly rated comments.

defaultExpansionThreshold

It can be set to expand all or collapse all. By default, its value is set to collapse all. If set to expand all, it will expand all the filtered comments, show description, rating menu, and allow user to post reply via links.

viewDiscussionWindow

A user configurable property. If set to true, the discussion link gets displayed on an entire page; that is, JSPDynamicSingleContainer is invoked. If set to false, the discussion gets displayed within the channel within the tab.

anonymousAuthor

An anonymous user can submit comments. Default author value for an anonymous user is picked from this property. Default value is anonymous. For example, it can be set to unknown author.

displaySearch

Enable or disable Search in discussions.

showDescription

Specifies whether or not to show a description of the discussion.

ratingText

Specifies the type of rating that can be done on a discussion. By default, discussions can be rated as irrelevant, routine, interesting, important, or must read. This property is not used in this release.

SubscriptionsProvider

SubscriptionsProvider provides subscriptions service to users. The Subscriptions service enables users to create a set of profile of interest over a source of information. The source of information supported are categories, discussions, and searchable documents. The profile is updated with the latest information every time the user accesses the Subscriptions channel. The Subscriptions channel summarizes the number of hits (relevant information) that matches each profile entry the user defined for categorized document and/or discussions.

Chapter 23 Display Profile Properties: Content Provider Properties

This section provides definitions and examples for the following content providers that ship with the Portal Server software.

• AddressBookProvider, LotusNotesAddressBookProvider, and MSExchangeAddressBookProvider

• AppProvider, BookmarkProvider, LoginProvider and NotesProvider

• CalendarProvider, LotusNotesCalendarProvider, and MSExchangeCalendarProvider

• IMProvider

• SimpleWebServiceProvider and SimpleWebServiceConfigurableProvider

AddressBookProvider, LotusNotesAddressBookProvider, and MSExchangeAddressBookProvider

The address book provider works with the Sun Java System Messaging Server to provide simple personal address book functionality.

The list of properties specific to AddressBookProvider, LotusNotesAddressBookProvider, and MSExchangeAddressBookProvider and their description are:

String name="sunPortalABSortBy"

Specifies the value of the entries displayed to sort by.

String name="sunPortalABSortOrder"

Specifies the sort order of the entries displayed.

String name = "ssoAdapter"

Specifies the SSOAdapter configuration used by this provider/channels.

Integer name="maxEntries"

Specifies the limit for the number of address book entries to display.

Integer name="numEntries"

Specifies the number of entries to display.

Boolean name="displayEntries"

Specifies if the entries should be shown.

Collection name="applicationHelperEdit"

Specifies the mail application helpers that you can edit settings on.

String name="applicationHelperURL"

Specifies the default mail application helper.

Collection name="ssoEditAttributes"

Specifies the attributes that will appear on the 1st edit page for the provider. These are usually server settings and have nothing to do with display profile attributes.

Collection name="dpEditAttributes"

Specifies the attributes that will appear on the edit page for the application helper. These are usually display attributes and there can be multiple attributes based on number of clients, and so on.

Collection name="sunPortalABSortBySelectOptions"

Used to generate the drop down select boxes on the edit page. This specifies None and Full name.

Collection name="sunPortalABSortOrderSelectOptions"

Used to generate the drop down select boxes on the edit page. This specifies Ascending, Descending, and None.

AppProvider

AppProvider enables a user to add or remove applications from a list of applications.

The list of properties specific to AppProvider and their description are:

String name="windowPref"

Specifies how to launch a link. The possible values are:

• all_new (New window is opened for every link)

• one_new (All links open on the same new window)

• same (Desktop window)

Collection name="targets"

Specifies the list of application links in name | URL format, where name should match should match the entry in the userApps collection.

Collection name="userApps"

Specifies the list of applications that appear in the applications channel.

BookmarkProvider

BookmarkProvider enables a user to add or remove URLs from a list of bookmarks.

The list of properties specific to BookmarkProvider and their description are:

String name="windowPref"

Specifies how to launch a link. The possible values are:

• all_new (New window is opened for every link)

• one_new (All links open on the same new window)

• same (Desktop window)

Collection name="targets"

Specifies the list of bookmarks that is shown in the channel in the following format:

BookmarkName|URL

CalendarProvider, LotusNotesCalendarProvider, and MSExchangeCalendarProvider

The CalendarProvider works with the Sun Java System Calender Server so that you can view tasks and events and launch Calendar Express without having to sign in. The LotusNotesCalendarProvider works with the Lotus Notes Server so that you can view tasks and events and launch the web application without having to sign in. The MSExchangeCalendarProvider works with the Microsoft Exchange Server so that you can view tasks and events and launch Exchanges web application.

The list of properties specific to CalendarProvider, LotusNotesCalendarProvider, and MSExchangeCalendarProvider and their description are:

String name="view"

Specifies the view (day, week, or month) used.

String name="calendar"

Specifies the calendar to display.

String name="ssoAdapter"

Specifies the ssoAdapter configuration to use.

Boolean name="loadSubscribedCalendars"

If set to true, it will try to load all of the subscribed calendars and display them.

Boolean name="disableTaskEventURLs"

If set to true, it will not display links for tasks and events.

Collection name="calendarSelectOptions"

Specifies a list of all subscribed calendars.

Collection name="applicationHelperEdit"

Specifies the mail application helpers that you can edit settings on

String name="applicationHelperURL"

Specifies the default mail application helper

Collection name="ssoEditAttributes"

Specifies the attributes that will appear on the 1st edit page for the provider. These are usually server settings and have nothing to do with display attributes

Collection name="dpEditAttributes"

Specifies the attributes that will appear on the edit page for the application helper. These are usually display attributes and there can be multiple attributes based on number of clients, etc.

Collection name="viewSelectOptions"

Specifies the different Calendar views displayed in the Calendar edit page.

IMProvider

The IMProvider includes:

• Information needed to help the user decide whether to launch the IM (Instant Messenger) client.

• The ability to launch the IM client using single-sign-on.

The information is gathered by accessing the Instant Messaging server through the use of the Instant Messaging APIs.

The list of properties specific to IMProvider and their description are:

mux

Specifies the name of instant messaging multiplexor to use (used by IM client.)

muxport

Specifies the port on which the instant messaging multiplexor listens.

codebase

Specifies where to find the instant messaging client.

netletRule

Specifies where to find the instant messaging client when using the netlet. By default, the value is IM.

clientRunMode

Specifies how the Instant Messaging server client must be run. The client can be run as either a plugin or jnlp. By default, the value is plugin.

authMethod

Specifies the authentication method. Clients can authenticate either via idsvr (for Sun Java System Access Manager) or ldap. By default, the value is idsvr.

authUsernameAttr

Specifies the LDAP attribute where instant messaging username is found. By default, the value is uid.

username

Specifies the username for LDAP authentication. This is not applicable if authMethod is set to idsvr.

password

Specifies the password for LDAP authentication. This is not applicable if authMethod is set to idsvr.

contactGroup

Specifies the contact group to display, or blank for all.

LoginProvider

LoginProvider enables the Login channel to show up in the anonymous user’s Desktop. You can configure LoginProvider to enable users to log in and out using the Login channel. The system administrator can select one out of the three methods to enable users to log in: LDAP, Membership, or UNIX.

For the sample portal, if you specify the following URL in a browser, you see the authlessanonymous user’s Desktop, which contains the login channel.

http://hostname:port/portal/dt

By default, LoginProvider uses Membership authentication. No additional setup is required to use this channel. From the authlessanonymous user page, valid users can use the login channel, and new users can register using the Sign me up link in the channel. You can change the authentication module for the login channel.

The properties, which are specific to the LoginProvider and their description are:

Boolean name="persistentCookie"

Specifies if a persistent cookie is used to remember the user ID and password.

Boolean name="federationEnabled"

If set to true, the libertyLogin.Template is inserted.

String name="preLoginURL"

The value specified in the channel. This property is typically of the form:

http://www.siroe.con:80/amserver/preLogin? metaAlias=www.siroe.com& goto=http://www.siroe.com:80/portal/dt

NotesProvider

NotesProvider enables the administrator or users the administrator has authorized to post a note to all users’ Desktops in the Notes channel.

The list of properties specific to NotesProvider and their description are:

String name="location"

Specifies the path to the text file, which contains the notes, in the file system.

String name="lines"

Specifies the number of lines of notes that is displayed in the channel.

String name="maxLines"

Specifies the maximum number of lines that can be displayed in the channel.

Integer name="timeout"

Specifies the time zone of the time stamp at which the notes were logged, either as an abbreviation such as PST, a full name such as America/Los_Angeles, or a custom ID such as GMT-8:00. Support of abbreviations is for JDK™ 1.1.x compatibility only and full names should be used.

Notes are stored and read in a text file in the following format:

userid | date | message

where | is the delimiter and date is the long value that denotes the time elapsed in milliseconds since January 1, 1970.

Example of a sample notes file:

User1|1007159465858|Message to Portal Desktop Team : Lets meet today at 2PM
User2|1007159465858|Information related to project is availble at home page

SimpleWebServiceProvider

SimpleWebServiceProvider, an extension of JSPProvider, makes simple web services available to an end user channel. SimpleWebServiceProvider dynamically constructs a user interface given a Web Services Description Language (WSDL) URL and a web service method name.

Using the URL, SimpleWebServiceProvider fetches the WSDL document, parses and validates it. Based on its content, SimpleWebServiceProvider generates input parameters to the method that return the information from the web service. The information is then displayed in the channel content window.

SimpleWebServiceProvider can generate channels that use the same web service, and the same method, so default parameter values can be stored using the Edit function.

SimpleWebServiceProvider supports basic data types such as String, int, and float as defined in the WSDL specification. It supports Complex Types if they are made up of only basic types (one level of nesting). There is no support for arrays.

SimpleWebServiceProvider can provide WSDL parsing for any other provider that needs it. SimpleWebServiceProvider is designed for stock quote or currency exchange rate content.

The list of properties specific to SimpleWebServiceProvider and their description are:

String name="wsdlURL"

Specifies the URL to web service WSDL.

String name="methodName"

Specifies the web service method name that is going to be executed.

Boolean name="isDefaultShowOutput"

Specifies the default value. If true, the channel uses the default input value. If false, the channel uses the user input value.

String name="contentPage"

Specifies the JSP that is used to generate the channel content (by using the getContent() method).

String name="editPage"

Specifies the JSP that is used to generate the Edit page content (by using the getEdit() method).

Boolean name="showExceptions"

If true, makes SimpleWebServiceProvider show exceptions generated while processing the JSP as the channel output for the getContent() and getEdit() methods. This can be useful for developing and troubleshooting your portal.

Boolean name="isDefaultAvailable"

If true, the default value is available from the profile database.

Collection name="defaultInput"

Specifies the default input value.

SimpleWebServiceConfigurableProvider

SimpleWebServiceConfigurableProvider is similar to SimpleWebServiceProvider, except that it permits users to use the Edit function to change URLs and methods, hence, it is configurable.

The list of properties specific to SimpleWebServiceConfigurableProvider and their description are:

String name="wsdlURL"

Specifies the URL to web service WSDL.

String name="methodName"

Specifies the web service method name that is going to be executed.

Boolean name="isDefaultShowOutput"

Specifies the default value. If true, the channel uses the default input value. If false, the channel uses the user input value.

String name="contentPage"

Specifies the JSP that is used to generate the channel content (by using the getContent() method).

String name="editPage"

Specifies the JSP that is used to generate the Edit page content (by using the getEdit() method).

Boolean name="showExceptions"

If true, makes SimpleWebServiceConfigurableProvider show exceptions generated while processing the JSP as the channel output for the getContent() and getEdit() methods. This can be useful for developing and troubleshooting your portal.

Boolean name="isDefaultAvailable"

If true, the default value is available from the profile database.

Collection name="defaultInput"

Specifies the default input value.

Chapter 24 Display Profile Common Properties for Leaf Providers

Providers contain required properties and general properties. This chapter contains the following sections, which describe the general properties of providers.

• Introduction

• Common Properties

• Other Leaf Provider Display Profile Properties

Introduction

By editing the provider properties in the display profile XML files, you can create customized display profile provider definitions. Any time you modify a display profile document, use the psadmin command (or the administration console) to store it in LDAP.

The Portal Server software sample portal display profile XML fragments define the default values for all expected properties, so that channels that use the supplied providers do not have to define all the properties, only the ones that need to be different.

Depending on the merge priorities and locking assigned to the display profile documents that make up a user’s display profile, the ultimate property values that are returned to a user’s Desktop can change.

Common Properties

The list of common properties for a <Provider> definition and their description is provided below. In addition to the following properties, there are properties that are used in specific providers. For example, the lines and maxLines properties are required by the notes provider code.

title

Specifies the title that appears in the channel title bar in the Desktop.

description

The description is displayed on the content page to give the user a little more information about what the channel is more. For example:

title: Bookmarks description: manage your portal-specific bookmarks

refreshTime

The refreshTime property controls how often a channel’s content is reloaded.

editType

Specifies the edit type, either edit_complete or edit_subset. If edit_complete, the provider’s getEdit() method is responsible for generating the complete Edit page content. If edit_subset, a generic edit provider container is used to put a frame around the Edit page. The provider’s getEdit() page is then called, and displays the content of the Edit page.

isEditable

Determines if the provider has an edit view. If true, the Edit button is generated in the channel title bar. By clicking the Edit button, users can display an Edit page and customize channel settings such as whether the channel is minimized or detached. The Edit page is generated by the Provider.getEdit() method.

If isEditable is false, no edit view is provided and no Edit button is generated in the title bar and users cannot change the settings for the channel. To implement an editable provider, the default no-operation implementations of ProviderAdapter.getEdit() and ProviderAdapter.processEdit() must be overridden.

If the provider has the getEdit() and processEdit() methods defined, you can change the value of isEditable from false to true to cause the Edit button to appear in the channel title bar.

width

A channel’s width setting is a suggestion for containing channels as to how much screen real estate the channel may require. This value is only a suggestion; a container is not required to utilize this value for its contained channels. Possible values are thin, thick, full_top, or full_bottom. In general, these values only make sense for an HTML-based Desktop.

helpURL

Specifies the online help URL, which can be either a fully qualified URL value or a relative path to the doc root location. For example, the online help URL for the bookmark channel is:

http://hostname:port/portal/docs/en/desktop/bkmark.html

This URL could also be defined as desktop/bmark.html. In this case, the provider context code figures out the doc root and the user locale, and locates the online help URL.

A return value of null signifies that this provider does not have a help page.

To have the provider code not generate a Help icon on the title bar for the channel, use a value of “”.

fontFace1

Specifies the default font face for the channel, for example, Sans-serif.

productName

Specifies the name of the product, for example, Sun Java System Portal Server. This is not required by all providers.

Required properties and their values for the <Provider> definition are based on the Provider interface. The required properties are necessary for the provider code if the provider class extends ProviderAdapter or the ProfileProviderAdapter class. Note that the channel can set its own properties that override these values.

Other Leaf Provider Display Profile Properties

authlessState

The authlessState property determines how client specific state is managed when the Desktop is operating in authless mode. Client specific state is accessed via the ProviderContext.get/setClientProperty() methods. The authlessState client type property can take on three values: client, server, and none. When set to:

• client, authless state is stored on the client.

• server, authless state is stored on the server.

• none, no authless state is recorded and the ProviderContext.get/setClientProperty() methods have no effect.

By default, the authlessState client type property is not present, and defaults to client for HTML devices, and none for non-HTML devices. To modify the default value for a specific client type, add the authlessState client type property and set its value to either client, server, or none.

encoderClassName

The encoderClassName client type property maps an encoding algorithm (class) to a specific client type. This information is used by the ProviderContext.escape() method to escape strings in a client type specific manner.

ConditionalProperties

This provides a generic operation for retrieving conditional properties. The most common conditions are locale and clientType, but the API is generic in that it allows you to define and base properties on any sort of condition.

In the administration console, the conditional properties are displayed as condition-value and can be edited like collections. The conditional properties can be nested and can be added to a channel or inside another conditional property. Use the Add Property page to add a new conditional property.

The <ConditionalProperties> tag must be used to define the filtering criteria. The tag contains the following required attributes:

condition

Specifies name of the filter

value

Specifies the value to be used in the filter

In the display profile, the <ConditionalProperties> tag can be defined as outlined in the following example.

Example 24–1 <ConditionalProperties> Tag Usage Sample

<Properties>
    <String name="foo" value="bar">
    <ConditionalProperties condition="locale" value="de">
        <String name="foo" value="german bar">
        <String name="baz" value="a german baz value">
    </ConditionalProperties>
    <ConditionalProperties condition="client" value="nokia">
        <ConditionalProperties condition="locale" value="de">
            <String name="foo" value="nokia german bar">
        </ConditionalProperties>
    </ConditionalProperties>
</Properties>

Chapter 25 Display Profile Channel Properties

The provider definition is the template that decides the properties for a channel. However, the display profile channel definition ultimately decides the values for the channel attributes. The display profile channel definition can define properties that overwrite the properties defined by the provider definition.

Display Profile Channel Properties

Container channels are channels that primarily generate its content by aggregating the content of other (its child) channels. A container channel allows for available and selected channel lists (see “Available and Selected List” on page 49) and can contain leaf channel definitions.

Both container and leaf channel properties can be configured from the administration console. See the provider-specific display profile properties for more information on the channel properties.