Chapter 4   Display Profile Properties


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

This chapter contains the following sections:

• Overview of Display Profile Properties

• Display Profile Global Properties

• Display Profile Provider Required Properties

• Display Profile Container Provider Properties

• Display Profile Provider General 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

In addition, you can set global properties, which affect all channels.

By customizing a provider's property values, you can customize all channels that the provider generates. By customizing an individual channel's properties, you customize that particular channel.

You associate properties with the following display profile objects:

• <Properties> definition

• <Provider> definition

• <Channel> definition

• <Container> definition

The display profile groups properties inside of a properties "bag," which is kind of holding place for properties. The property itself does not have a properties bag associated with it.

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.

---

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 doesn't make sense here, thus a channel would naturally override this value. See "Display Profile Provider Required Properties" for more information.

Properties set in the <Container> definition 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 (minimized or detached). See "Display Profile Container Provider Properties" for more information.

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 5, "Administering Sun ONE Portal Server Display Profile," in the Sun ONE Portal Server 6.0 Administrator's Guide for a complete discussion of display profile properties.

Display Profile Global Properties

---

Use global properties to assign properties that apply to all channels. For example, Code Example 4-1 shows the global properties defined in the dp-org.xml display profile that is part of the sample portal. You assign the global properties in the <Properties> </Properties> definition by using tags such as <Collection> </Collection>, <String> </String>, <Integer> </Integer>, and so on.

---

Code Example 4-1    dp-org.xml Display Profile 

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

<Properties>

<Collection name="GlobalThemes" propagate="false">

<Collection name="theme1">

<String name="description" value="Sun ONE"/>

<String name="bgColor" value="#FFFFCC"/>

<String name="titleBarColor" value="#330066"/>

<String name="fontColor" value="#330066"/>

<String name="borderColor" value="#FF9933"/>

<String name="borderWidth" value="1"/>

<String name="fontFace" value="Verdana"/>

</Collection>

<Collection name="theme2">

<String name="description" value="Sun"/>

<String name="bgColor" value="white"/>

<String name="titleBarColor" value="#666699"/>

<String name="fontColor" value="black"/>

<String name="borderColor" value="#9999CC"/>

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

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

</Collection>

</Collection>

<String name="UserTheme" value="theme2" propagate="false"/>

<Collection name="CustomTheme" propagate="false">

<String name="bgColor" value=""/>

<String name="titleBarColor" value=""/>

<String name="fontColor" value=""/>

<String name="borderColor" value=""/>

<String name="borderWidth" value=""/>

<String name="fontFace" value=""/>

</Collection>

<Collection name="locales">

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

</Collection>

<String name="docroot" value="/docs/"/>

<String name="helpURL" value="desktop/usedesk.htm"/>

</Properties>

...

</DisplayProfile>

Table 4-1 shows all the global attributes. This two column table lists the attributes in the first column and a brief description in the second column.

Table 4-1    Display Profile Global Attributes  

Attribute	Description
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 "Adding and Customizing 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, 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 pulldown list.
docroot	Specifies the online help doc root relative to the installed portal/static location. See the Javadocs for the getHelp() method in ProviderContextProvider.java.
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.

Display Profile Provider Required Properties

---

Required properties and their values for the <Provider> definition are based on the provider interface. The required properties are necessary for the provider code, but the channel can set its own properties that override these values.

In addition to the following required properties, there are properties that are used in specific providers. For example, the lines and maxLines properties are required by the notes provider code. You can also define other properties in the <Provider> definition. For example:

<Provider name="MyProvider" class="com.sesta.providers.MyProvider">   <Properties>     ... required properties ...     <String name="authorInfo" value="John Doe (john.doe@sesta.com)"/>   </Properties> </Provider>

The Sun™ ONE Portal Server sample display profile defines 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.

---

Note

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. See Chapter 5, "Administering the Display Profile," in the Sun ONE Portal Server 6.0 Administrator's Guide for more information on merging.

---

Table 4-2 lists the required properties for a <Provider> definition. This two column table lists the properties in the first column and a brief description in the second column.

Table 4-2    Required Properties for Display Profile <Provider> Definition  

Property Tag	Description
title	Specifies the channel name. The title appears in the channel title bar in the Desktop. You can localize the title string in the display profile as follows: <Locale language="en" country="US">   <String name="title" value="This is the sample title"/> </Locale> <Locale language="en" country="UK">   <String ... </Locale>
description	Specifies the provider description.
refreshTime	Specifies the time interval to fetch content for a channel. If the channel content does not change frequently, define refreshTime greater than 0 (zero) so that the content is not fetched each time the Desktop container is drawn. This saves on channel processing time. If refreshTime is 0 (the default), then the browser refresh causes the page to be reloaded and the getContent() method is called again for every channel.
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. If isEditable is false, no edit view is provided and no Edit button is generate in the title bar. See "isEditable Property Tag" for more information.
width	Determines the final channel's width. Values are thin, thick, full_top, or full_bottom.
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://server: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 ONE Portal Server.

isEditable Property Tag

The isEditable property tag determines if the provider has an edit view. When isEditable is set to 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 getEdit() method.

When isEditable is set to false, the Edit button is not generated in the channel title bar and users cannot change the settings for the channel. 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. If the provider does not have the getEdit() and processEdit() methods defined, then you need to extend the provider class to support these two methods, which are necessary to generate the Edit page for the channel.

Most channels set the DTD element attribute advanced equal to true for isEditable, so that the property is not visible in the iPlanet™ Directory Server Access Management Edition admin console Channel and Container Management link. By causing the property to not be displayed in the admin console, it cannot be changed there. You can, however, edit the property by using the Edit XML link in the admin console.

The following providers must have the isEditable property tag is set to false, as there is no code for handling the Edit page:

• URLScraperProvider

• XMLProvider

• RSS (a channel of XMLProvider)

You would need to extend these providers to enable them to have an edit view. See the Sun ONE Portal Server 6.0 Developer's Guide for more information on how to extend a provider.

The following providers can have the isEditable property tag set to true or false, but can only be used by an authorized user, such as the administrator:

• NotesProvider

• MailCheckProvider

The following providers have the isEditable property tag set to true by default, though you can change isEditable to false if you do not want users to be able to customize the channels:

• UserInfoProvider

• BookmarkProvider

• AppProvider

• JSPProvider

• SimpleWebServiceProvider

• SearchProvider

Display Profile Container Provider Properties

---

Container building-block providers must set required properties, and optionally, can set other properties as well.

Container Required Properties

Table 4-3 shows the required container properties. This two column table lists the property tags in the first column and a brief description in the second column.

Table 4-3    Container Required Properties  

Property Tag	Description
Available	Defines a list to contain all available channels for this container. The available channels are displayed in the content preference page for users to select from. The <Available> and </Available> tags define the list, and the <Reference value=> tag defines the list items. For example: <Available>     <Reference value="UserInfo"/>     <Reference value="MailCheck"/>     <Reference value="App"/>     <Reference value="Bookmark"/> </Available>
Selected	Defines a list to contain selected channels for this container. Only selected channels shows up in the Desktop. The <Selected> and </Selected> tags define the list, and the <Reference value=> tag defines the list items. For example: <Selected>     <Reference value="UserInfo"/>     <Reference value="MailCheck"/>     <Reference value="App"/>     <Reference value="Bookmark"/> </Selected>

Other Required Container Properties

Table 4-4 shows the other required container properties, which are necessary for the out-of-the box sample Desktops. This two column table lists the property tags in the first column and a brief description in the second column. The <Collection name> </Collection> tags define a list to contain these properties, which are set with the <String> tag.

---

Note	The requirement for these properties is based on Sun ONE Portal Server's out-of-the-box implementation of the container providers. If you change your implementation, then the required properties could also change.

---

Table 4-4    Other Container Properties  

Property Tag	Description
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.
thin_popup_height	Defines the window height in pixels for the thin channel in the detached window.
thin_popup_width	Defines the window width in pixels for the thin channel in the detached window.
fullwidth_popup_height	Defines the window height in pixels for the full_top or full_bottom channel in the detached window.
fullwidth_popup_width	Defines the window width in pixels for the full_top or full_bottom channel in the detached window.
defaultChannelIsMinimizable	Defines the isMinimizable default value for the channels in this container. If you define a default value, then you do not have to define isMinimizable for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelIsMinimized	Defines the isMinimized default value for the channels in this container. If you define a default value, then you do not have to define isMinimized for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelIsDetached	Defines the isDetached default value for the channels in this container. If you define a default value, then you do not have to define isDetached for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelIsDetachable	Defines the isDetachable default value for the channels in this container. If you define a default value, then you do not have to define isDetachable for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelIsRemovable	Defines the isRemovable default value for the channels in this container. If you define a default value, then you do not have to define isRemoveable for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelHasFrame	Defines the hasFrame default value for the channels in this container. If you define a default value, then you do not have to define hasFrame for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelIsMovable	Defines the isMovable default value for the channels in this container. If you define a default value, then you do not have to define isMovable for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelColumn	Defines the column number default value for the channels in this container. If you define a default value, then you do not have to define the column number for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
defaultChannelRow	Defines the row number default value for the channels in this container. If you define a default value, then you do not have to define row number for all the leaf channels in the container. You can change the value for a leaf channel in the container if needed.
channelsIsMinimized	Defines a collection property to contain the isMinimized value for channels in this container.
channelsIsDetached	Defines a collection property to contain the isDetached value for channels in this container.
channelsHasFrame	Defines a collection property to contain the hasFrame value for channels in this container.
channelsIsMinimizable	Defines a collection property to contain the isMinimizable value for channels in this container.
channelsRow	Defines a collection property to contain the row number value for channels in this container.
channelsColumn	Defines a collection property to contain the column number value for channels in this container.
channelsIsMovable	Defines a collection property to contain the isMovable value for channels in this container.
channelsIsDetachable	Defines a collection property to contain the isDetachable value for channels in this container.
channelsIsRemovable	Defines a collection property to contain the isRemovable value for channels in this container.
borderlessChannels	Defines the collection property to contain the channel name and Boolean value pair for specifying borderless channels in this container. A value of true means the channel does not have border.
defaultBorderlessChannel	Defines the default value for the borderless channels in this container. If you define a default value, then you do not have to define borderlessChannels for all leaf channels in the container. You can change the value for a leaf channel in the container if needed.

Properties for JSP-based Table, Tab, and Frame Tab Containers

The table and tab containers (both JSP- and template-based) have a Content page for users to select channels to be displayed. This page is generated from the display profile <Collection name="categories"> </Collection> tags. The channels in the container are grouped based on the categories that are defined in the display profile.

---

Note	For the template-based Desktop, the Content page is the same as the iPlanet™ Portal Server 3.0 style, where channels are grouped based on channel width. Thus, the categories property is not required for the template-based containers.

---

Each container can have different categories, which is the case for the sample portal. First, you define a collection of categories in the display profile. Then, for each value in that collection, you define another collection named as the value of the categories.

For example, the following defines two channels, Personal Channels and Sample Channels, with two links each.

<Collection name="categories">     <String value="Personal Channels">     <String value="Sample Channels"> </Collection> <Collection name="Personal Channels"> <--category one     <String value="UserInfo"/>     <String value="MailCheck"/>     </Collection> <Collection name="Sample Channels"> <--category two     <String value="SampleJSP">     <String value="SampleXML"> </Collection>

Required Properties for Tab Containers

Tab containers (both JSP- and template-based tab containers) need a way to enable users to dynamically create new tabs and populate those new tabs with default properties. The collection property TabProperties creates the new tab, and the collection property propertiesToCopy provides the initial properties for the new tab.

TabProperties Collection Property Example

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. See Code Example 4-2.

---

Code Example 4-2    TabProperties Collection Property Example  

<Collection name="TabProperties">

<Collection name="MyFrontPageTabPanelContainer">

<String name="title" value="My Front Page"/>

<String name="desc" value="Your front page"/>

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

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

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

</Collection>

<Collection name="SamplesTabPanelContainer">

<String name="title" value="Samples"/>

<String name="desc" value="Samples Tab"/>

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

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

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

</Collection>

<Collection name="JSPTabCustomTableContainer">

<String name="title" value="Make My Own Tab"/>

<String name="desc" value="Make from Scratch"/>

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

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

<Boolean name="predefined" value="false"/>

</Collection>

</Collection>

<Collection name="SearchTabPanelContainer">

<String name="title" value="Search"/>

<String name="desc" value="Search Tab"/>

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

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

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

</Collection>

</Collection>

defaultChannelList Collection Property

The defaultChannelList collection property describes a list of channels that are included in the available and selected lists for a newly created tab. See Code Example 4-3.

---

Code Example 4-3    defaultChannelList Collection Property Example

<Collection name="defaultChannelList">   <String value="UserInfo"/>   <String value="MailCheck"/>   <String value="App"/>   <String value="SampleSimpleWebService"/>   <String value="Bookmark"/>   <String value="SampleJSP"/>   <String value="SampleRSS"/>   <String value="SampleXML"/>   <String value="Notes"/>   <String value="SampleURLScraper"/>   <String value="Search"/> </Collection>

propertiesToCopy Collection Property

The propertiesToCopy collection property sets the initial properties to be defined in a newly created tab container. See Code Example 4-4.

---

Code Example 4-4    propertiesToCopy Collection Property Example

<Collection name="propertiesToCopy">

<String value="timeout"/>

<String value="title"/>

<String value="description"/>

<String value="refreshTime"/>

<String value="width"/>

<String value="helpURL"/>

<String value="fontFace1"/>

<String value="productName"/>

<String value="contentPage"/>

<String value="layout"/>

<String value="Desktop-fontFace1"/>

<String value="isEditable"/>

<String value="editType"/>

<String value="presetThemeChannel"/>

<String value="customThemeChannel"/>

<String value="thin_popup_height"/>

<String value="thin_popup_width"/>

<String value="thick_popup_height"/>

<String value="thick_popup_width"/>

<String value="fullwidth_popup_height"/>

<String value="fullwidth_popup_width"/>

<String value="categories"/>

<String value="defaultChannelIsMinimizable"/>

<String value="defaultChannelIsMinimized"/>

<String value="defaultChannelIsDetached"/>

<String value="defaultChannelIsDetachable"/>

<String value="defaultChannelIsRemovable"/>

<String value="defaultChannelHasFrame"/>

<String value="defaultBorderlessChannel"/>

<String value="channelsIsMinimized"/>

<String value="channelsHasFrame"/>

<String value="channelsColumn"/>

<String value="channelsRow"/>

<String value="channelsIsMinimizable"/>

<String value="channelsIsDetachable"/>

<String value="channelsIsDetached"/>

<String value="channelsIsRemovable"/>

<String value="channelsIsMovable"/>

<String value="borderlessChannels"/>

</Collection>

In Code Example 4-4, these properties are copied from the tabcustomtablecontainer provider to the newly created tablecontainer channel.

If you change the makeTabProvider to a different container provider, you also need to modify the propertiesToCopy collection based on the required properties for makeTabProvider.

Other Required Properties

The list of other required properties for tab containers is:

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

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

  
  

  ---

  Note

  Contained table containers have a display profile property called parentTabContainer whose value is the name of the tab container in which the contained table container is contained. If the contained table container has to be used in some other tab container, change this property value to the respective tab container name.

  ---

  
  

Display Profile Provider General Properties

---

Table 4-5 lists the other properties for provider definitions. These can be used with leaf and container building-block 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 4-5    Display Profile General Properties

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

---

Note	See Chapter 5, "Administering Sun ONE Portal Server Display Profile," in the Sun ONE Portal Server 6.0 Administrator's Guide for information on the following document type definition attributes: advanced lock merge priority propagate

---