Sun ONE logo     Previous     Contents     Index     Next     
Sun ONE Portal Server 6.0 Desktop Customization Guide



Chapter 1   Introduction to Customizing the Desktop


This chapter provides an introduction to customizing the Sun™ ONE Portal Server Desktop. It describes the different kinds of customizations and who would 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 Sun ONE Portal Server Desktop can be customized by end users, administrators, and developers. Though this guide covers only administrator customizations, it does present overviews of end user and developer customizations, and where to go for more information on those customizations. This guide refers to administrator customizations 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:

  • Setting the channel time out

  • Selecting column layout

  • Moving channels up and down, as well as side to side

  • Arranging channels by width

  • Adding and removing certain channels

  • Customizing channels by using the channel Edit page

  • Setting the color scheme and font type for the Desktop

  • Creating, removing, and editing tabs

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 Sun ONE Portal Server End User Desktop Online Help for more information.

Users can also configure:

  • Time zone, language, mail server, and password by using the User Info Edit page.

  • Personal and mail information by using the iPlanet™ Directory Server Access Management Edition admin console. The URL to use is:

    http://servername:port/amconsole

Developer Customizations

Sun ONE Portal Server developers can customize the Desktop by creating:

  • Provider classes

  • Desktop templates

  • Tag libraries

  • JavaServer Pages

Developers can also use the Provider Application Programming Interface (PAPI) and search APIs to extend Sun ONE Portal Server. See the Sun ONE Portal Server 6.0 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 iPlanet Directory Server Access Management Edition APIs. See the iPlanet Directory Server Access Management Edition 5.1 Programmer's Guide for more information.

Administrator Customizations

Sun ONE Portal Server administrators can customize the Desktop by:

  • Using supplied providers to define additional content channels.

  • Creating and customizing the display profile, which involves creating or modifying provider, channel, and container channel objects. When you modify the display profile, you use the appropriate XML tag definitions for providers, channels, and container channels.

  • Using supplied JavaServer Pages and template files to modify the interface.

  • Customizing the search provider.

  • Customizing the Desktop end user online help.

By performing these customizations, you can arrive at:

  • A site-specific look and feel of the Desktop: whether it uses tabs or frames, what channels are available to users and how they are situated out on the Desktop, what applications are available to end users, what kind of online help is available, and so on.

  • Different Desktops for different LDAP roles or organizations.

  • Desktop behavior based on user roles.

This guide describes these administrator customizations.

Using the Display Profile

Much of your work in customizing Sun ONE Portal Server 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) controls how the display profile functions. See /opt/SUNWps/dtd/psdp.dtd for more information.

As confusing as it may sound, the display profile does not actually define the overall layout or organization of what users see on their Desktops. Fundamentally, the display profile exists only to provide property values for channels.

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. Still other building blocks provide the content to channels, and hence are referred to as "providers."


Note Sun ONE Portal Server distinguishes between building-block providers, which you can extend using the Sun ONE Portal Server APIs, and content providers, which you cannot extend. See the Sun ONE Portal Server 6.0 Developer's Guide for more information on extending providers.


Using the display profile mechanism, you can create a new portal 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 iPlanet Directory Server Access Management Edition services layer. Potentially, Sun ONE Portal Server 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 users's display profile is "dynamic" because it can consist of multiple display profile documents, which are "merged" at runtime to form a single Desktop representation.

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, isp.com. Next is the DN, sesta.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 Chapter 5, "Administering the Display Profile," in the Sun ONE Portal Server 6.0 Administrator's Guide for more information.

Figure 1-1    Example of Merge Process
Example of display profile merge process.

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 programmatic entity responsible for the generation of content, which is displayed in the channel. The XML tag for defining a provider object is <Provider name=>.

  • Channel object - 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=>.

  • Channel 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 group 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, and global 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, and how the merging works, see Chapter 5, "Administering Sun ONE Portal Server Display Profile," in the Sun ONE Portal Server 6.0 Administrator's Guide.

See Appendix B, "XML Reference," in the Sun ONE Portal Server 6.0 Administrator's Guide, for a description of the display profile DTD syntax.

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>

<Properties>, <Channels>, and <Providers> are mechanisms to do grouping. These mechanisms make the XML display profile document more structured, so that like objects are in each "bag."

The following sections describe the display profile objects in more detail. For a complete discussion of the display profile, see Chapter 5, "Administering Sun ONE Portal Server Display Profile," in the Sun ONE Portal Server 6.0 Administrator's Guide.

DisplayProfile root Object

The DisplayProfile root container object enables the Desktop servlet to act as a container provider to get handles to providers and so forth. There is no actual provider class associated with the channel. This channel should not be referenced by any other display profile object.

DisplayProfile root Object XML Syntax

<Container name="_desktopRoot" provider="none">

   <Properties/>

   <Available/>

   <Selected/>

   <Channels/>

</Container>

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

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:

  • JSPProvider

  • XMLProvider

  • URLScraperProvider

The container building-block providers include:

  • Tab

  • Table

  • Single

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"/>
...
    <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 correct. 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 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="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 ONE 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:

  • Using the iPlanet Directory Server Access Management Edition admin console Channel and Container Management link.

  • Using the iPlanet Directory Server Access Management Edition admin console Edit XML link.

  • Manually editing an existing display profile document then loading it at the appropriate LDAP node by using the dpadmin modify command.

  • Running the dpadmin command with the specified XML text changes, on standard input. When adding a new object you use the add subcommand. When modifying an existing object, you use the modify subcommand.

  • Creating a new display profile document from scratch then loading it at the appropriate LDAP node by using the dpadmin modify command.

For information on using the dpadmin command, see Chapter 12, "Command-Line Utilities," in the Sun ONE Portal Server 6.0 Administrator's Guide.

Where to Go for More Information

See Chapter 2 "Display Profile Provider Definitions," and Chapter 3 "Display Profile Channel Definitions" for the display profile provider and channel definitions provided by Sun ONE Portal Server. See Chapter 5 "Understanding the Sample Portal" for a description of the sample portal components (display profile, and JavaServer Pages or templates).

Using JavaServer Pages and Template Files

To generate the rendered Desktop user interface (what the industry refers to as the "presentation"), Sun ONE Portal Server makes use of either JavaServer Pages (JSP™) or template files (HTML). 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.

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


If you choose to install the sample portal, the installer locates the JSP and template files in the /etc/opt/SUNWps/desktop/default and /etc/opt/SUNWps/desktop/anonymous directories. The Desktop Type attribute in the Desktop attributes page of the iPlanet Directory Server Access Management Edition admin console specifies from what subdirectory to retrieve either the JSP or template files for the Desktop. The default for this attribute is default, meaning files are retrieved from the default subdirectory.


Note The relationships between the Desktop files stored under the /etc/opt/SUNWps/desktop directory and what is configured by using the iPlanet Directory Server Access Management Edition admin console and display profiles is provider-specific.

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 properties file is fixed, for example, display.template, and that name is mentioned in the documentation for the provider.


The Desktop and JavaServer Pages

The Desktop servlet uses the display profile to retrieve the data for a channel to display. The channel data specifies the provider class to use. In the case of a JSP-based channel, this is the JSPProvider class. The JSPProvider class reads the data (in the form of properties) to retrieve and the name of the JSP to display. 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

The template files are not defined in the display profile and thus are not as flexible or easy to use as JSPs. The provider code decides what template files to load, based on the hard-coded template names in the provider, and uses the getTemplate() method to retrieve the template. The template files are not public, and so you cannot extend them nor change the class. This is another reason that JSPs are easier to use and customize.

The Desktop HTML templates were used in iPlanet™ Portal Server 3.0 and are included for backward compatibility only. See Appendix A "Desktop Template and Tag Reference" for more information.


Note To ensure backward compatibility with iPlanet Portal Server 3.0, it is possible in Sun ONE Portal Server 6.0 to have Desktop channels that are HTML template based. If you are migrating from iPlanet Portal Server 3.0 Service Pack 4 to Sun ONE Portal Server 6.0, you can migrate your HTML templates. In Sun ONE Portal Server 6.0, the templates are located in the /etc/opt/SUNWps/desktop/default directory, in the TemplateTableContainer and TemplateTabContainer subdirectories. See the Sun ONE Portal Server 6.0 Migration Guide for more information.


To Change the Desktop Type

You can define a new set of templates by creating a new directory under the /etc/opt/SUNWps/desktop/ directory, placing your template files in this directory, and making this directory the Desktop Type attribute for that organization.

  1. Create a new subdirectory in the /etc/opt/SUNWps/desktop directory, or whatever directory templateBaseDir specifies in the desktopconfig.properties file.

    For example:

    mkdir /etc/opt/SUNWps/desktop/sesta

  2. Manually copy all template files to the new directory location.

  3. Use the iPlanet Directory Server Access Management Edition admin console to change the value of the Desktop Type attribute for the subdirectory created in Step 1. As this attribute is dynamic, you need to change it everywhere that it appears (organization, sub-organization, role, and user).

    In this example, you would specify sesta as the value.

    See the Sun ONE Portal Server 6.0 Administrator's Guide for more information on editing Desktop attributes.


    Note The Desktop service uses a dynamic attribute, SunPortalDesktopDefaultChannelName, which is shown as Default Channel Name in the iPlanet Directory Server Access Management Edition console. This attribute specifies the channel/container to use when displaying the Desktop. By default, this attribute is set to JSPTabContainer for the sample portal. In addition to using the admin console to configure this attribute, you can use the PAPI setAttribute() method to specify a different default Desktop channel. For example, you could specify a table or frame Desktop rather than a tabbed Desktop by setting the attribute to a different container.

    However, setting this attribute is not recommended. Instead, use a routing container. A routing container is a channel that reads a display profile property specifying the user's preferred default Desktop channel to determine the Desktop to present. See the Sun ONE Portal Server 6.0 Developer's Guide for more information on routing containers.


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 requires the use of a tag library, which Sun ONE Portal Server supplies. Not all Desktop channels need to be JSP-based. Channels migrated from iPlanet Portal Server 3.0 still work using HTML-based templates.

A tag library is exposed through Tag Library Descriptors (TLD) files, so tags are in their appropriate functional area. Table 1-1 shows the TLD files used for the JSP-based Desktop. This two column table lists the TLD files in the first column and a brief description in the second column. See Appendix B "JavaServer Pages Tag Library Reference" for more information.


Table 1-1    Tag Library Descriptors for the JSP-Based Desktop  

Tag Library Descriptor File

Description

desktop.tld  

Contains core Desktop tags.  

desktopContainerProviderContext.tld  

Contains tags to operate on container providers that extend the JSPContainerProviderAdapter interface.  

desktopProviderContext.tld  

Contains tags to operate on providers that extend the ProviderContext interface.  

desktopSingle.tld  

Contains tags for the JSPSingleContainerProvider interface.  

desktopTab.tld  

Contains tags for JSPTabContainerProvider interface.  

desktopTable.tld  

Contains tags for the JSPTableContainerProvider interface.  

desktopTheme.tld  

Contains tags for theme support in the Desktop.  

JSPTL - jr.tld  

Contains the JSPTL (JavaServer Pages Tag Library) tags that accept rtexprvalues for their attributes.  

JSPTL - jx.tld  

Contains the tags that accept attribute values specified using the JSPTL "expression languages."  

search.tld  

Contains core Search Engine tags.  

What Is the Sample Portal?

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


Note Do not directly edit any of the files that make up the sample portal (display profile XML, JSP, and template files). Instead, make a copy of the sample portal to a new directory and modify those copied files. In this way you preserve the integrity of the sample portal. Additionally, if you later apply a patch to the portal server, you won't loose any changes you might have made to the sample portal files, as the patch would only overwrite the initially installed sample files.


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 no 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. See the Sun ONE Portal Server 6.0 Developer's Guide for more information on developing custom providers.

Table 1-2 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-2    Sun ONE 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 5 "Understanding the Sample Portal," for a complete description of the sample Desktop containers and how they function.

Creating a New Desktop

Creating a new Desktop involves seven basic steps:

  1. Developing the container

  2. Editing the display profile

  3. Developing JSPs or template files

  4. Deploying JSP or template files

  5. Loading the display profile at the appropriate LDAP nodes

  6. (Optional) Creating a resource bundle

  7. Testing access to the new Desktop

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.


    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 the location by editing the /etc/opt/SUNWps/desktop/desktopconfig.properties file.


Note You can also use the iPlanet Directory Server Access Management Edition admin 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 Provider Definitions" for more information.


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

Java class:
com.sun.portal.providers.containers.jsp.table.JSPTableContainerProvider


Developing 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/default directory, in different subdirectories for each container.

See Chapter 5 "Understanding the Sample Portal," Appendix A "Desktop Template and Tag Reference," and Appendix C "JavaServer Pages Reference" for more information on the sample JSP and template files.

Deploying JSP or Template Files

When you create a container, you need to create a new subdirectory in the /etc/opt/SUNWps/desktop/default directory for that container, and 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 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.

Also, because the value for editType is edit_subset, you don't need to specify the editPage for this container. It uses the default JSP-based edit channel, which is defined in the iPlanet Directory Server Access Management Edition admin console Desktop service page under the Default Edit Channel Name attribute. In the sample portal, this attribute has the value JSPEditChannel. The Edit page for that channel is edit.jsp and the processPage is doedit.jsp. These two JSPs are located in the /etc/opt/SUNWps/desktop/default/JSPEditContainer directory.

JSP and Template Files Lookup Scenario

Sun ONE Portal Server uses a specific lookup scenario to find the JSP and template files it needs for containers. The lookup scenario relies on the following parameters.

  • Desktop type, for example default (set in iPlanet Directory Server Access Management Edition admin console)

  • Preferred Locale, for example, en_US (set by users through the iPlanet Directory Server Access Management Edition admin console in the "User" setting)

  • Client type, for example html (set through the iPlanet Directory Server Access Management Edition admin console Client Detection service)

  • Channel name, for example, newSingleContainer (set in the display profile)

  • Provider name, for example, JSPSingleContainerProvider (set in the display profile)

Based on the above parameters, the lookup scenario would search for the JSPs in the example in this order:

/etc/opt/SUNWps/desktop/default_en_US/newSingleContainer/html/newsinglecontent .jsp

/etc/opt/SUNWps/desktop/default_en_US/JSPSingleContainerProvider/html/newsingl econtent.jsp

/etc/opt/SUNWps/desktop/default_en_US/newSingleContainer/newsinglecontent.jsp

/etc/opt/SUNWps/desktop/default_en_US/JSPSingleContainerProvider/newsinglecont ent.jsp

/etc/opt/SUNWps/desktop/default/newSingleContainer/newsinglecontent.jsp (The system finds it here.)

/etc/opt/SUNWps/desktop/default/JSPSingleContainerProvider/newsinglecontent.js p

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

See "To Change the Desktop Type" for more information on how to modify the Desktop type.

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 iPlanet Directory Server Access Management Edition admin console (as long as you aren't using Netscape 4.7x) or the Upload link.

See the Sun ONE Portal Server 6.0 Administrator's 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 need to create a resource bundle file with the same name as the provider. See "Creating and Extending a Provider Class" for more information.

Accessing the Desktop

You can access the Desktop in one of the following ways:

  1. Use a specific container or channel reference by using the ?provider argument to the Desktop login URL:

    http://server:port/portal/dt?provider=providername

    where providername is one of the providers listed in Table 1-2.

    For example, to access the JSP-based tab Desktop, in a browser, type:

    http://server:port/portal/dt?provider=JSPTabContainer

  2. 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.)

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

Creating and Extending a Provider Class

A provider is responsible for providing 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 PAPI. Sun ONE Portal Server 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 leaf channel providers are extended from the ProfileProviderAdapter class.

When you create a new provider, you also must create a resource bundle file with the same name as the provider. Strings defined in the resource bundle file appear in the Desktop but they are not channel properties, such as a string in the Edit page. For example, the bookmark channel contains a prompt, "Open each page in its own window." This is defined in the resource bundle so that it can be localized. The resource bundle name must be the same as the provider name. For example, if the bookmark provider is:

<Provider name="BookmarkProvider" class="com.iplanet.portalserver.providers.bookmark.BookmarkProvider">

the resource bundle file must be bookmark.properties.

See the Sun ONE Portal Server 6.0 Developer's Guide for details about creating and extending a provider class.

Deploying Providers and Channels

The par command enables you to transfer or move providers or channels from one Sun ONE Portal Server to another. The par utility creates a specialized packaging mechanism called a .par file for transport of channels and providers into and out of the server. A .par file is an extended form of the .jar file format, with added manifest information to carry the deployment information and an XML document intended for integration into the Sun ONE Portal Server display profile on the target server.

The use of .par files is optional. You can just as well copy all files into their correct locations. The par utility makes deployment easier if you have to install the files on multiple servers.

To create a .par file from scratch, use the jar or export subcommand of the par utility.

To export an existing provider, use the export subcommand of the par utility.

All providers that ship with Sun ONE Portal Server are in the service-level Desktop display profile. There is no command to extract them all.

See the Sun ONE Portal Server 6.0 Administrator's Guide for information on the par command, and creating and deploy .par files.


Previous     Contents     Index     Next     
Copyright 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated August 29, 2002