Chapter 2 Display Profile Properties

Sun ONE Portal Server 6.2 Desktop Customization Guide

Chapter 2
Display Profile Properties

This chapter describes the display profile global properties, and provider and channel specific properties.

This chapter contains the following sections:

Overview of Display Profile Properties

Display Profile Global Properties

Overview of Display Profile Properties

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.

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 associate properties with the following display profile objects:

<Properties> definition

<Provider> definition

<Channel> definition

<Container> definition

There are three 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" for more information.

Note

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.

Note

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.

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 the Sun ONE Portal Server 6.2 Administrator’s Guide for a complete discussion of the semantics of the display profile merging.

Display Profile Property Types

Table 2-1 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.

Table 2-1  Display Profile General Property Types

Property Type

Definition

Example

Boolean

An atomic object representing a Boolean value.

<Boolean name="removable" value="true"/>

Collection

An object representing either a list or hash table. A collection is a type of property, or named bag, in which to put other properties.

<Collection name="channelsRow">

    <String name="MailCheck" value="4"/>

    <String name="App" value="5"/>

</Collection>

ConditionalProperty

Defines the filtering criteria. 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. condition and value are required attributes.

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.

<ConditionalProperties condition="locale">

    <String name="en_US" value="English (United States)"/>

</ConditionalProperties>

Integer

An atomic object representing an integer value.

<Integer name="numberOfHeadlines" value="7"/>

Reference

An object representing a pointer to a channel definition (that is, to a channel name in a container’s selected and available channel lists.) Reference is an unnamed string useful for design tools to be able to distinguish such things from strings.

<Reference value="UserInfo"/>

String

An atomic object representing a string value.

<String name="title" value="Table Container Channel 1"/>

Display Profile 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, Code Example 2-1 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.

Code Example 2-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 following is a list of all the global attributes available with the default installation of the sample portal. This two column table lists the attributes in the first (left) column and a brief description in the second (right) column.

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" 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.

locales

Used by UserInfoProvider to form the Language pull-down list.

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.

Previous      Contents      Index      Next

Copyright 2003 Sun Microsystems, Inc. All rights reserved.


Note	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.


Note	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.

Property Type	Definition	Example
Boolean	An atomic object representing a Boolean value.	<Boolean name="removable" value="true"/>
Collection	An object representing either a list or hash table. A collection is a type of property, or named bag, in which to put other properties.	<Collection name="channelsRow"> <String name="MailCheck" value="4"/> <String name="App" value="5"/> </Collection>
ConditionalProperty	Defines the filtering criteria. 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. condition and value are required attributes. 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.	<ConditionalProperties condition="locale"> <String name="en_US" value="English (United States)"/> </ConditionalProperties>
Integer	An atomic object representing an integer value.	<Integer name="numberOfHeadlines" value="7"/>
Reference	An object representing a pointer to a channel definition (that is, to a channel name in a container’s selected and available channel lists.) Reference is an unnamed string useful for design tools to be able to distinguish such things from strings.	<Reference value="UserInfo"/>
String	An atomic object representing a string value.	<String name="title" value="Table Container Channel 1"/>

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" 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.
locales	Used by UserInfoProvider to form the Language pull-down list.
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.