Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Portal Server 6 2004Q2 Desktop Customization Guide 

Chapter 1
Introduction to Customizing the Desktop

This chapter provides an introduction to customizing the Sun Java System Portal Server software Desktop. It describes the different kinds of customizations and who should make those customizations. This chapter also provides an overview of the display profile, sample Desktops included with the product, and how you create and deploy a new Desktop and provider.

This chapter contains the following sections:


Types of Desktop Customizations

The Desktop can be customized by end users, administrators, and developers. Though this guide covers only administrator customizations, it includes an overview of end user and developer customizations, and where to go for more information on those customizations. This guide refers to administrator customizations such as changes and modifications made to the Desktop that involve modifications to the display profile, JavaServer Pages™ and template files, search provider, and online help.

End User Customizations

End users can customize the Desktop in the following ways:

Users customize channels by using the Edit Channel icon for a particular channel (as long as the administrator has made it available). Users customize the look and feel of the Desktop through the Themes page. See the Portal Server software End User Desktop Online Help for more information.

Users can also configure:

Developer Customizations

The Portal Server software developers can customize the Desktop by creating:

Developers can also use the Provider Application Programming Interface (PAPI) and the Search service APIs to extend the Portal Server software. See the Portal Server Developer’s Guide for more information.

In addition, developers can create new portal services to integrate applications and enable Single Sign-on across multiple applications, as well as implement authentication modules, using the Identity Server software APIs. See the Identity Server Programmer’s Guide for more information.

Administrator Customizations

The Portal Server software administrators can customize the Desktop by:

By performing these customizations, you can arrive at:

This guide describes these administrator customizations.


What Are the Areas for Customizing the Desktop?

In general, the Portal Server software documentation divides Desktop interface customization into three areas:

Authentication screens    

You can modify the look and feel of the HTML authentication templates, including images, HTML structure, and color.


Note

Authentication screens are provided by the Identity Server software. This guide does not describe how to customize the authentication screens. See the Identity Server Programmer’s Guide for that information.


Desktop    

You can modify the look and feel of the Desktop, customize the top container used by the organization, control Desktop themes, and so on. This chapter describes the Desktop customization tasks.

Files for dynamic content for providers, channels, and containers are located under the /etc/opt/SUNWps/desktop directory; that is, the Base Desktop templates are in /etc/opt/SUNWps/desktop/default and sample portal templates are in /etc/opt/SUNWps/desktop/sampleportal directories. For more information, see What Is the Sample Portal?.

Some other static resources are located in the web-container/portal directory. This includes images used on the Desktop, such as channel control buttons, and style sheets.


Note

References to the locations and contents of files in the web-apps directory are for information only. They do not represent the definition of an interface that you can depend on for any future release.


Search channel    

You can modify the default Search server and add or remove fields from the Advanced search interface. See Chapter 14, "Customizing the Service Providers" for more information.


Using the Display Profile

Much of your work in customizing the Portal Server software involves creating or editing the display profile to provide the kind of Desktop you want for your site. The display profile is an XML document that defines the Desktop structure and content. The display profile Document Type Definition file (DTD) defines valid syntax for the display profile XML documents. See /etc/opt/SUNWps/dtd/psdp.dtd for more information.

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.


Note

A provider is a Java class responsible for converting the content in a file, or the output of an application or service into the proper format for a channel. A number of providers are shipped with the Portal Server software. As the desktop is imaged, each provider is queried in turn for the content of its associated channel. Some providers are capable of generating multiple channels based upon their configuration.


Using the display profile mechanism, you can create a new portal Desktop or modify the sample portal provided with the product. See What Is the Sample Portal? for more information.

Display profile documents are stored in their entirety as a single attribute in the Identity Server 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.

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

For example, Figure 1-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. See the Portal Server Administration Guide for more information.

Figure 1-1  Example of Merge Process

This figure shows a sample merge process of the display profile documents.

The display profile documents themselves consist of display profile objects. The display profile DTD defines the XML tags that represent the allowable display profile objects. These are:

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

The display profile document for a provider provides default property values for all properties that channels based on that provider will use. It provides the class name to use to create the provider object (see Provider object for more information) at runtime.

Channel object    

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. The XML tag for a channel is <Channel name=“channelName” provider=“providerName”> and the XML tag for a container channel is <Container name="containerName" provider="providerName">.

A display profile channel definition defines the configuration for a Desktop channel. Specifically, it defines the provider Java object that is used to create a running channel instance (indirectly, by naming the display profile provider definition that names the Java class file), and defines the properties used by the channel instance. Only property values that differ from the defaults defined in the associated display profile provider definition should be defined in the display profile channel definition’s properties. See also, Channel object.

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. See also, Property object.

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.

For a complete discussion of the display profile, how the merging works, and a description of the display profile DTD syntax, see the Portal Server Administration Guide.

Display Profile Document Structure

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 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 DP XML documents.

The following sections describe the display profile objects in more detail. For a complete discussion of the display profile, see the Portal Server Administration Guide.

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.

Code Example 1-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:///etc/opt/SUNWps/desktop/default/SampleXML/getQuotes.xml"/>

        <String name="xslFileName" value="/etc/opt/SUNWps/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.

The leaf building-block providers include:

The container building-block providers include:

See the Portal Server Developer’s Guide for more information on the leaf and container building-block providers.

Code Example 1-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>

    <Available>

        <Reference value="UserInfo"/>

        <Reference value="MailCheck"/>

        ...

    </Available>

    <Selected>

        <Reference value="UserInfo"/>

        <Reference value="MailCheck"/>

        ...

    </Selected>

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

</Container>

Provider Object

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 provider definition contains the information necessary for a client of the display profile to construct the provider object, namely, the Java™ class name.

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.

Code Example 1-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:///etc/opt/SUNWps/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>

Modifying the Display Profile

You can modify display profile objects by performing one of the following:

For information on using the dpadmin command, see the Portal Server Administration Guide. Use the following guidelines when running the dpadmin command to update the display profile:


Using JavaServer Pages and Template Files

To generate the rendered Desktop user interface (what the industry refers to as the “presentation”), The Portal Server software makes use of either JavaServer Pages (JSP™) or template files. JSPs are preferred because they enable a much easier customization process without having to change the provider Java classes. JSPs also provide a way to enable a strict separation of business and presentation logic. Specifically, this means having the business logic in the provider classes and presentation logic in JSPs.


Note

In general, a three-tier architecture consists of presentation logic, business logic, and the data. Tag libraries or Enterprise JavaBeans™ provide the business logic, a database contains the data, and JavaServer Pages (JSPs) or templates provide the presentation logic. However, this view is based on a “small” system where the entire system is contained in one server, or perhaps only the data is on another server.

The Portal Server software takes the “larger” system view, where all of the product is presentation. The business logic resides in some back end resource server that a content provider accesses. The data is on yet another back end server. Because all of the Portal Server software is presentation, there really is no business logic in the product.


The default set of JSPs and template files are installed in /etc/opt/SUNWps/desktop/default directory. The sample portal JSPs and template files are installed in /etc/opt/SUNWps/desktop/sampleportal and /etc/opt/SUNWps/desktop/anonymous directories. The Desktop Type attribute in the Desktop attributes page of the Identity Server software administration console specifies from what subdirectory to retrieve either the JSP or template files for the Desktop. For more information, see JSP and Template Files Lookup Scenario.


Note

How the JSPs and Template files are referenced by the providers is provider-specific. Some providers specify the file in the display profile, other providers specify fixed names.

For example, for JSPProvider, there are display profile properties such as contentPage, editPage, and so on, that reference Desktop files under the /etc/opt/SUNWps/desktop directory. For other providers, such as BookmarkProvider, the name of the template file is fixed, for example, display.template and that name is mentioned in the display profile document for that provider.


The Desktop and JavaServer Pages

The JSPProvider class reads in the JSP, compiles it, and runs it to produce the channel content.

The JSPProvider class reads at most three JSPs, one for content, one for the Edit page, and one to process the form submission from the Edit page. All other JSPs used in a JSP-based channel are referenced from one of those JSPs, either by an include or a forward statement.

A simple JSP-based channel can have just one JSP. Multiple JSPs are useful when a single part of the Desktop has to be replicated in several places. For example, consider a channel that has several display modes based on links clicked in that channel. Further, assume that the channel has a banner that must be displayed in all modes but one. You could construct a JSP to reference a banner.jsp file that captures common formatting that is used in multiple branches of the logic. If you didn’t use this method, you would need to duplicate the content from the banner.jsp file, which is more difficult to maintain if that content needs to be changed. See Appendix C, "JavaServer Pages Reference" for more information.

The Desktop and Template Files

Providers that use template files hardcode their names and the template file names are not configurable in the Display Profile. For Providers that are based on JSP provider, the names of the JSP used by provider can be administratively changed as it is a property of the channel.

Both JSP and Desktop templates serve the purpose of separating business and presentation logic in the Portal Server. JSP is an accepted standard and is widely employed in many web-based applications. Desktop templates pre-date the emergence of JSP. JSP has many advantages over Desktop templates.

It is highly recommended that new Portal Server providers be based on JSP and the Portal Server JSPProvider. However, there may be cases where the simplicity of Desktop templates provides an advantage. Desktop templates are fully supported in Portal Server. Many pieces of the product, such as the communications channels, continue to use them.

JSP and Template Files Lookup Scenario

The Portal Server software uses a specific lookup scenario to find the JSP and template files it needs for containers.

desktoptype_locale/channelname/clientPath

desktoptype_locale/provider/clientPath

desktoptype_locale/channelname

desktoptype_locale/provider

desktoptype_locale/clientPath

desktoptype_locale

desktoptype/channelname/clientPath

desktoptype/provider/clientPath

desktoptype/channelname

desktoptype/provider

desktoptype/clientPath

desktoptype

default_locale/channelname/clientPath

default_locale/provider/clientPath

default_locale/channelname

default_locale/provider

default_locale/clientPath

default_locale

default/channelname/clientPath

default/provider/clientPath

default/channelname

default/provider

default/clientPath

default

templateroot

If there is no clientPath specified, then the directory search order is as follows:

desktoptype_locale/channelname

desktoptype_locale/provider

desktoptype_locale

desktoptype/channelname

desktoptype/provider

desktoptype

default_locale/channelname

default_locale/provider

default_locale

default/channelname

default/provider

default

templateroot

The lookup scenario relies on the following parameters.

Use this order to decide the final location of your own JSPs.

Deploying JSP or Template Files

When you create a container, you need to create a new subdirectory for your newly created container in the /etc/opt/SUNWps/desktop/desktopType directory. That is, the newly created container should be placed based on what the desktopType is. If sampleportal is installed, then the desktopType is, by default, sampleportal; so, create a new directory for the container under sampleportal so that any JSP and template that is being added can adopt the same look and feel as defined in the sampleportal. If sampleportal is not installed, and if you have set up a custom desktopType, for example, foo, then the new container directory must be created directory under foo.

Either copy the modified JSP or template files here, or place your newly created files here. If you use a sample container without changing any content or file names, you do not need to create a new subdirectory nor copy any files there. (In the example that follows, a new subdirectory is needed, because a new container is created.)

For example, let’s say you create a new container called newSingleContainer whose display profile definition is the following:

<Container name="newSingleContainer" provider="JSPSingleContainer">

    <Properties>

        <String name="helpURL" value="desktop/newSingle.html"/>

        <String name="title" value="A new single container"/>

        <String name="contentPage" value="newsinglecontent.jsp"/>

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

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

    </Properties>

    <Available/>

    <Selected/>

    <Channels/>

</Container>

Because the file specified for the contentPage property is different from the contentPage value for the provider definition, you need to create a new directory under the /etc/opt/SUNWps/desktop/default directory called newSingleContainer. You then only need to copy the newsinglecontent.jsp file to this new directory. The system is able to locate all other JSPs referenced by the JSPSingleContainer provider.

Creating Customized Organization JSP and Template Files

If desired, rather than customizing the sample portal JSP and template files directly, you can create a separate directory for your organization’s customized files, and perform customizations on those files. This preserves the initially installed portal JSP and template files.

    To Create Customized Organization JSP and Template Files
  1. Change directories to the Desktop JSP or template directory.
  2. For example,

    cd /etc/opt/SUNWps/desktop

  3. Create a new directory for your organization’s JSPs and templates.
  4. For example,

    mkdir sesta

  5. Copy the JSPs and templates that you wish to modify into the new directory location, maintaining the same directory structure.
  6. For example, if your new Desktop type will modify /etc/opt/SUNWps/desktop/default/JSPProvider/content.jsp, copy this file to /etc/opt/SUNWps/desktop/sesta/JSPProvider/content.jsp, and customize the file for the new Desktop type in that location.

  7. Customize the JSPs templates in the sesta directory as required.
  8. Change the dynamic Desktop Type attribute in the Identity Server software administration console to use the newly created directory.
  9. See Changing the Desktop Type for more information.

Using the Desktop Tag Library

Desktops based on JSPs enable a customization process without the necessity of changing the provider Java classes. The implementation of the JSP-based Desktop uses a tag library which the Portal Server software supplies. Not all Desktop channels need to be JSP-based. There are also channels using HTML-based templates.

A tag library is exposed through Tag Library Descriptors (TLD) files, so tags are in their appropriate functional area. See Appendix D, "JavaServer Pages Tag Library Reference" for more information.


What Is the Sample Portal?

Conceptually, the Desktop is split into the following three well-defined components (see Figure 1-2 also):

Base Desktop    

This includes Provider Java classes (based on the Provider API), provider display profile definitions and resource bundles (also referred to as properties files), display profile definitions of channels referenced by base Desktop XML or base Desktop JSPs and templates, default templates and JSPs (installed in /etc/opt/SUNWps/desktop/default directory), and help files.

Sample portal    

This includes organization level display profile definitions (such as themes and channel display profile definitions), templates and JSPs for the example Desktops in the sample portal (installed in /etc/opt/SUNWps/desktop/sampleportal directory), and user definition, Desktop display profile definitions, and templates and JSPs for the Authless user.

Other components    

This includes the Provider Java classes for their component specific providers, provider display profile definitions for their component specific providers and provider resource bundles (properties files), display profile definition for channels referenced by component display profile XML or component templates and JSPs, default templates and JSPs, and help files.

The sample portal has a dependency on the base Desktop and other components and cannot be installed if the base Desktop and other components are not installed. The base Desktop and other components are installed as part of the Portal Server software.

Figure 1-2  Desktop Components

This image shows the components that make up the Desktop.

When you install the Portal Server software, you can choose to install the sample portal. The sample portal includes five example Desktops that show the possibilities of the Portal Server software. In this way you can quickly get a feel for the kinds of containers that are possible to design.

Table 1-1 shows the five Desktops, which make up the sample portal. This two column table lists the containers (Desktops) in the first column and a brief description in the second column.

Table 1-1  Sun Java System Portal Server Sample Desktop Containers  

Container (Desktop) Type

Description

JSPTabContainer

Generates a JSP-based tab Desktop.

JSPTableContainer

Generates a JSP-based table Desktop.

TemplateTableContainer

Generates a template-based table Desktop.

TemplateTabContainer

Generates a template-based tab Desktop.

FrameTabContainer

Generates a frame-based Desktop.

See Chapter 3, "Understanding the Sample Portal" for a complete description of the sample Desktop containers and how they function.

The sample portal can also serve as a place to start when building your own site’s portal. You can customize the containers and use the building-block providers, such as XMLProvider and JSPProvider, to add customized content. The sample portal also includes content providers, such as BookmarkProvider, that cannot be extended but that can be used to provide content.

If the existing building-block and content providers do not meet your needs, you can either extend an existing building-block provider (content providers are not public and hence not extendible), or develop custom building-block providers. If either of these methods do not suit your needs, you can develop a custom provider.


Note

The Portal Server software distinguishes between building-block providers, which you can extend using the Portal Server software APIs, and content providers, which you cannot extend. See the Portal Server Developer’s Guide for more information on extending the providers.



Creating a New Desktop

Creating a new Desktop involves the following:

The following sections describe each of these steps in detail.

Developing the Container

You can develop a container by:

  1. Defining a <Container> element in the display profile that references an existing <Provider> element.
  2. Defining a <Provider> element in the display profile that references an existing provider class. You also must do Step 1.
  3. Defining a container provider class that extends an existing container provider such as JSPTableContainerProvider. You also must do Step 2.
  4. Defining a container provider class from scratch that extends ContainerProviderAdapter. You also must do Step 2. If you create a container by extending the Provider class, then it also needs to implement the ContainerProvider interface.

  5. Note

    You cannot create a container provider by just extending the Provider class. By definition, a container must implement the ContainerProvider interface. ContainerProviderAdapter does this.


If you write a new class file, it must reside in the /etc/opt/SUNWps/desktop/classes directory. You can change this location by editing the /etc/opt/SUNWps/desktop/desktopconfig.properties file.


Note

You can also use the Identity Server software administration console to manipulate containers.


Editing the Display Profile

You need to edit the display profile XML and modify the following tag:

<Provider name="provider" class="provider class">

You also need to modify the following tag, which references the provider in the previous sentence:

<Container name="container" provider="provider">

For JSP files, the <Properties> tag for the provider contains the following property tag, which references the JSP Content page:

<String name="contentPage" value="value">

The <Properties> tag for the channel can have values that override the properties set in the <Provider> tag. Thus, if desired, you could set the JSP contentPage value here. You do not reference template-based providers, or other providers you might develop, in this way.

The <Available> and <Selected> tags are required for all containers in the display profile.

The JSP-based tab, table, and frametab containers have additional properties requirements. See Chapter 2, "Display Profile Properties" for more information.


Note

There is a distinction between a provider element in the display profile and the Java class for the provider.

Provider element:

<Provider name="JSPTableContainer" class=com.sun.portal.providers.containers.jsp.table.JSPTab leContainerProvider>

Java class:

com.sun.portal.providers.containers.jsp.table.JSPTableCont ainerProvider


Developing and Deploying JSP or Template Files

You can modify existing JSP files (for example, tabs.jsp) or template files, or develop with your own. If you install the sample portal, the JSP and template files are located in the /etc/opt/SUNWps/desktop/sampleportal directory, in different subdirectories for each container.

See Appendix A, "Desktop Template Files" and Appendix C, "JavaServer Pages Reference" for more information on the sample JSP and template files.

For the JSPs, you can find compilation and runtime errors in the desktop debug log at /var/opt/SUNWam/debug/desktop.debug. Also, all JSPProvider based Desktop channels have a property called showExceptions. By default, this property is set to false; setting it to true causes the JSP exception to show up as the content of the channel.

When you create a container, you need to create a new subdirectory for your newly created container in the /etc/opt/SUNWps/desktop/desktopType directory. That is, the newly created container should be placed based on what the desktopType is. If sampleportal is installed, then the desktopType is, by default, sampleportal; so, create a new directory for the container under sampleportal so that any JSP and template that is being added can adopt the same look and feel that as defined in the sampleportal. If sampleportal is not installed, and if you have set up a custom desktopType, for example, foo, then the new container directory must be created directory under foo.

Either copy the modified JSP or template files here, or place your newly created files here. If you use a sample container without changing any content or file names, you do not need to create a new subdirectory nor copy any files there. (In the example that follows, a new subdirectory is needed, because a new container is created.)

For example, let’s say you create a new container called newSingleContainer whose display profile definition is the following:

<Container name="newSingleContainer" provider="JSPSingleContainer">

    <Properties>

        <String name="helpURL" value="desktop/newSingle.html"/>

        <String name="title" value="A new single container"/>

        <String name="contentPage" value="newsinglecontent.jsp"/>

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

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

    </Properties>

    <Available/>

    <Selected/>

    <Channels/>

</Container>

Because the file specified for the contentPage property is different from the contentPage value for the provider definition, you need to create a new directory under the /etc/opt/SUNWps/desktop/default directory called newSingleContainer. You then only need to copy the newsinglecontent.jsp file to this new directory. The system is able to locate all other JSPs referenced by the JSPSingleContainer provider.

Loading the Display Profile at the Appropriate LDAP Nodes

Load the display profile at the appropriate LDAP node(s) by using the dpadmin command. You can also use the Edit Display Profile XML text box in the Identity Server software administration console (as long as you are not using Netscape 4.7x) or the Upload link.

See the Portal Server Administration Guide for more information on the dpadmin command, and the Edit Display Profile XML text box and Upload link.

(Optional) Creating a Resource Bundle

If you created a new provider, you may need to create a resource bundle file with the same name as the provider.

Accessing the Desktop

Access the Desktop in one of the following ways.

    To Access the Desktop
  1. Use a specific container or channel reference by using the provider argument to the Desktop login URL:
  2. http://hostname:port/portal/dt?provider=providername

  1. If no channel is referenced, the Desktop looks in the session for the last channel or container that was displayed. (This is stored in the session.)
  2. If no channel is stored in the session, the Desktop looks in a Desktop service attribute for the top-level container to display (Default Channel Name attribute). This happens after an initial login.

Once this top-level container is determined, that container draws the containers or channels that it references (through the Selected list), until all of its leaves have been reached.

Debugging the Desktop

Use the following to help debug the Desktop environment:

The Desktop debug file is located at:

/var/opt/SUNWam/debug/desktop.debug

If you get an error message page on the Desktop, you can view the source to look at the stack trace. (For example, in Netscape Navigator, select Page Source from the View menu.)


Creating and Extending a Provider Class

A provider is responsible for delivering the content for a channel as well as defining the various channel properties such as title and description. A provider can optionally implement edit functionality.

You create a provider by creating a new provider class. The provider class is a Java class that implements all the methods defined in the Provider interface. The Portal Server software supplies basic implementation classes that implement the provider interface, ProviderAdapter. The ProfileProviderAdapter extends ProviderAdapter and adds some convenient methods that are indirectly defined in the ProviderContext class. Most of the time, you will extend ProfileProviderAdapter for your provider class. All building-block and content providers extend the ProfileProviderAdapter, either directly or indirectly.

See the Portal Server Developer’s Guide for details about creating and extending a provider class.



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.