Sun Java System Portal Server 7.1 Developer Sample Guide

Chapter 3 Creating a New Desktop

Creating a new Desktop involves the following:

Developing the Container

When developing a container, you can do the following:

Define a <Container> element in the display profile that references an existing <Provider> element. For example, to create a custom Container definition that uses the JSPTabContainerProvider:
```
<Container name="MyTabContainer" provider="JSPTabContainerProvider">
		<Properties/>
		<Available/>
		<Selected/>
		<Channels/>
</Container>
```

Define a <Provider> element in the display profile that references an existing container provider class. You must also define the container. For example, create the custom Provider definition that uses the JSPTabContainerProvider container provider class:

<Provider name="MyTabContainerProvider" class="com.sun.portal.providers.containers.jsp.tab.JSPTabContainerProvider">
		<Properties/>
</Provider>

<Container name="MyTabContainer" provider="MyTabContainerProvider">
		<Properties/>
		<Available/>
		<Selected/>
		<Channels/>
</Container>

Define a container provider class that extends an existing container provider such as JSPTabContainerProvider. You must also define the container in the display profile. For example:

public class MyTabContainerProvider extends JSPTabContainerProvider {
    }

<Container name="MyTabContainer" provider="MyTabContainerProvider">
		<Properties/>
		<Available/>
		<Selected/>
		<Channels/>
</Container>

Define a container provider class from scratch that extends ContainerProviderAdapter. You must also define the container in the display profile. If you create a container by extending the container provider class, then it also needs to implement the ContainerProvider interface:

public class MyTabContainerProvider extends ContainerProviderAdapter
		implements ContainerProvider {
}

<Provider name="MyTabContainerProvider" class="package.MyContainerProvider">
		<Properties/>
</Provider>

<Container name="MyTabContainer" provider="MyTabContainerProvider">
		<Properties/>
		<Available/>
		<Selected/>
		<Channels/>
</Container>

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. See the Sun Java System Portal Server 7.1 Developer’s Guide for more information on creating custom container providers.

If you write a new class file, it must reside in the PortalServer-DataDir/portals/portal-ID/desktop/classes directory. You can change this location by editing the PortalServer-DataDir/portals/portal-ID/config/desktopconfig.properties file. The providerClassBaseDir setting in the desktopconfig.properties file determines the directory where the classes will be picked up.

Editing the Display Profile

The developer needs to edit the display profile document and specify the <Container> and <Provider> display profile elements where applicable. The tags that should be modified are:

<Provider name="provider" class="provider class">
<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.

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

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

Using the Portal Server software administration console to download the display profile and uploading it after modifying it.
Manually editing an existing display profile document and then loading it at the appropriate LDAP node by using the psadmin modify-display-profile subcommand.
Creating a new display profile document from scratch and then loading it at the appropriate LDAP node by using the psadmin add-display-profile subcommand.

For more information on display profile and the psadmin subcommands to manage the display profile, see the Sun Java System Portal Server 7.1 Command Line Reference.

Developing and Deploying JSP or Template Files

The Developer Sample JSP and template files are located in the PortalServer-DataDir/portals/portal-ID/desktop/developer_sample directory. The JSP and template files can be copied to a custom directory and modified by the developer or the developer can create new JSP or template files for their deployment.

For the JSPs, you can find compilation and runtime errors in the desktop debug log at PortalServer-DataDir/portals/portal-ID/logs/portal-instance/portal.0.0.log. 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 PortalServer-DataDir/portals/portal-ID/desktop/desktopType directory. That is, the newly created container should be placed based on what the desktopType is. If the Developer Sample portal is installed, then the desktopType is, by default, developer_sample; so, create a new directory for the container under developer_sample so that any JSP and template that is being added can adopt the same look and feel that as defined in the sample portal. If sample portal is not installed, and if you have set up a custom desktopType, for example, foo, then the new container directory must be created directly 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 PortalServer-DataDir/portals/portal-ID/desktop/developer_sample 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.

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

Change directories to the Desktop JSP or template directory.

For example,
cd PortalServer-DataDir/portals/portal-ID/desktop

Create a new directory for your organization’s JSPs and templates.

For example,
mkdir sesta

Copy the JSPs and templates that you wish to modify into the new directory location, maintaining the same directory structure.

For example, if your new Desktop type will modify PortalServer-DataDir/portals/portal-ID/desktop/default/JSPProvider/content.jsp, copy this file to PortalServer-DataDir/portals/portal-ID/desktop/sesta/JSPProvider/content.jsp, and customize the file for the new Desktop type in that location.

Customize the JSPs templates in the sesta directory as required.

Change the dynamic Desktop Type attribute in the Portal Server software administration console to use the newly created directory.

Loading the Display Profile at the Appropriate LDAP Nodes

The display profile document for the Developer Sample exist at DNs similar to the following:

o=DeveloperSample,dc=sun,dc=com

Load the display profile at the appropriate LDAP node using the psadmin subcommands. You can also use the Edit Display Profile XML from the Portal Server software management console using the two links to download the display profile and upload the display profile. Download the display profile, make the necessary changes, and then upload it again through the Portal Server software management console.

See the Sun Java System Portal Server 7.1 Command Line Reference for more information on the psadmin subcommands.

(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. The provider resource bundle should be in PortalServer-DataDir/portals/portal-ID/desktop/classes directory.

Accessing the Developer Sample Portal Desktop

Access the Desktop in one of the following ways.

To Access the Desktop

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

http://hostname:port/portal-ID/dt?provider=provider-name

where provider-name is one of the providers. For example, to access the JSP-based tab Desktop, in a browser, type:

http://hostname:port/portal-ID/dt?provider=JSPTabContainer

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

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 Developer Sample portal desktop environment:

The Desktop debug file is located at PortalServer-DataDir/portals/portal-ID/logs/portal-instance/portal.0.0.log.

If you get an error message page on the desktop, you can view the source to look at the stack trace.