Sun Java System Portal Server 7 Enterprise Sample Guide

Chapter 3 Presenting Information on the Desktop

When you look at the Portal Desktop, you see a web page with columns and tabs along the top. Each column contains one or more channels (small windows). A channel contains a page that displays a specific type of information (such as news and search).

You can use the tabs to navigate and separate content by categories. Each top level tab can have multiple nested tabs. The Enterprise Sample uses two tabs: Home and My Portal. The Home page has the nested tabs News and Career.

This chapter discusses the following topics:

For detailed information on channels and tabs, see the Sun Java System Portal Server 7 Developer Sample Guide.

Understanding Channels

To the end user, a channel is a distinct area in the desktop, usually set off with a border and header row of icons. The icons enable users to configure the channel to their preference.

Channels are administered from the Portal Server administration console. The administration console allows you to create channels from pre-built as well as custom providers and to change channel preferences.

Channels can be implemented either as Providers or Portlets.

Note –

A “channel” is a Sun Java System Portal Server specific term. The portlet specification (JSR-168) does not use the term “channel”. Rather, the JSR-168 portlet specification uses the term “portlet window” to refer to a specific use of a portlet.

Desktop Providers

Providers are vertical channels that have a single use and can be reused (multiple channels can be created from a single provider) on a custom portal. Providers are Java class files based on the Provider API that can be used to construct both channels and page containers.

You can use the Portal Server pre-built providers such as JSPProvider, URLScraperProvider, and XMLProvider to implement channels without the need to write code.

For more information on the Provider API, see Sun Java System Portal Server 7 Developer’s Guide.

JSR-168 Portlets

Portlets function similarly to providers, however they are based on the API defined by the JSR-168 portlet specification.

The Sun Java System Portal Server includes the following sample portlets:

Notepad Portlet
JSPPortlet
Bookmark Portlet
Weather Portlet

Note –

Use the Portal Server management console of command-line utilities to deploy these portlets at the Enterprise Sample organization level.

The advantages to using portlets are as follows:

Portability. A portlet implemented using only the standard Portlet API and other standard J2EE interfaces, is portable to any JSR168 portlet specification-compliant portlet container.
Access to developers. As support for the portlet API grows with multiple vendor implementations, more developers are becoming familiar with the API.
Developer tools. Wider support may be available for developer tools to create portlets.
Web application integration. The portlet API is based on the Servlet API, making it is easier to integrate portlets with servlets and other standard web application components.

Note –

For more information on the portlets, see Sun Java System Portal Server 7 Developer’s Guide.

Adding Content to the Desktop Using Channels

Portal administrators can add content to the Portal Desktop by adding provider and portlet channels. The following procedures discuss how to create a channel, modify it’s properties, add it to the desktop and then verify that it is being displayed.

Suppose you want to create a channel, named MyChannel, that displays content from an external web page (for example, http://www.google.com). You use the following procedures:

Creating a URLScraper Channel

To Create a URLScraper Channel

The following steps show how to create a URLScraper channel. The same steps can be followed to create other Provider based and Portlet based channels.

Steps

Click the Portals tab.

Click the Portal-ID in the Portals list.

Select Enterprise Sample [Org] in the Select DN list.

Click Manage Containers and Channels.

By default, the View Type is set to ASCTabContainer [Default].

Click NewsContainer.

Click New Channel or Container in the NewsContainer page.

In the New Channel or Container wizard, specify the following and click Close after the channel or container has been successfully created.
1. Select Portal: portal-ID, DN: Enterprise Sample [Org], and Type: Channel and click Next.
2. Select radio button Provider Channel for Channel Type and click Next.
3. Select the URLScraperProvider from the Provider drop down list
4. Specify Channel or Container Name (for example, MyChannel) in the text field and click Next.
5. Review the settings and click Finish.
  
  The channel is now available and visible in the Enterprise Sample News tab and by default, is set to be available and selected.

Editing the Channel Properties

To Edit the Channel Properties

Steps

Click MyChannel under the NewsContainer.

In the MyChannel tasks and properties page, edit the following properties:

url

Change this property to a valid URL such as http://www.google.com.

title

Change this property value to the title you want to display on the channel title bar. For example, My Channel.

description

Change this property value to a small description of the channel. For example, This is a test channel.

Click Save.

Verifying that the URLScraper Channel Displays on the Desktop

To Verify that the URLScraper Channel Displays on the Desktop

After you have added the channel to your desktop, verify that it is visible.

Steps

Access the Enterprise Sample anonymous portal.

Setting up Channel Menus

The E nterprise Sample allows users to personalize their portal content in a number of ways such as, adding or removing channels, modifying the layout of the Portal Desktop, and customizing the presentation of each channel. The last item - customizing the presentation of each channel - can be done using the channel menu which appears as a pull down menu. To activate the menu, click the menu on the inverted triangle at the right top corner of each channel.

By default, each channel menu has the following options:

Show full page view: Makes the current channel as the only visible channel on the desktop. All other channels on the desktop are hidden. The full page state can be removed by clicking on the “Show normal view” option in the channel menu.
Show title bar only: This is similar to the minimized state of a window. In this state, only the title bar of the channel displays. The content of the channel is not fetched. Users can use this option to stack up a number of channels on the desktop and view the content of each channel selectively. The minimized state can be reversed by clicking on Show normal view option in the channel menu.
Show in new window: Detaches a channel from the desktop and shows it in a new popup browser window. The detached channel can be reattached to the desktop by clicking Close Channel in the detached channel’s menu.
Remove channel: Allows the user to remove a channel from the desktop. The channel can be restored on the desktop by reselecting it for display from the Page Content & Layout page.
View channel help: Displays channel help.

Channel Menu Design

The chan nel menu is implemented using DHTML layers. The Javascript API for creating and manipulating menus is implemented in popup.js which can be found at PortalServer-DataDir/portal/portal-ID/web-src/enterprise/js directory. This is the deployed copy of the Javascript file. Any changes to this file should be made here. Then redeploy Portal Server using PortalServer-base/bin/psadmin redeploy (Solaris).

The menu Javascript API provides methods to create new menus, add menu items, and specify actions for each menu item.

Customizing the Channel Menu

The chann el menu for the Enterprise Sample can be customized to add new menu items or remove menu items. Customizing the channel menu requires modification of JSP files shipped in the JSPTableContainerProvider located, by default, in the PortalServer-DataDir/portal/portal-ID/desktop/enterprise_sample/JSPTableContainerProvider directory. The menu for channels displayed in the desktop is created in channelMenubar.jsp file. The menu for the channels in the popup window state is created in popupChannelMenubar.jsp file. Any modifications to the channel menu should be made in both the above files so that the changes are reflected in regular desktop channels as well as in the popup channels.

To create a new pull down menu from a JSP file
window.<%=channelName% >= new Menu();
Note –
The variable, channelName, is a String that contains the unique name of the channel. This is required so that each channel menu has a unique identifier. Menu items can be added using the addMenuItem(String name, String action) method.

To add items which are not links

window.<%=channelName%>. addMenuItem("&#8212;&nbsp;Channel Menu&nbsp;&#8212;");

To add menu items with an associated action
window.<%=channelName%>.addMenuItem("Update Channel", "location=’<dtpc:getDesktopURL pathinfo="$pathInfo"/>’");
Note –
The above line shows how to add a menu item that redirects the browser to a different location when clicked.

To add a menu item that will open a popup window when clicked

window.<%=channelName%>.addMenuItem("Attach Channel",onClick="openUrlInParent(<dtpc:getDesktopURL/>?action=process&provider=<%=containerName%>&<%=containerName%>channelAction=attach&<%=containerName%>.targetProvider=<%=leafChannel%>’, true);
windowClosed(window.name); 
window.close();");

Similar Javascript actions can be associated with each menu item. Actions are invoked when you click on the menu item. Here are some examples.

To add menu item separators use addMenuSeparator() method. For example:
window.<%=channelName%>.addMenuSeparator();

To modify the appearance and operations, customize the following properties:

window.<%=channelName%>.fontColorHilite = "#FFFFFF";
window.<%=channelName%>.menuHiliteBgColor = "#F68947";
window.<%=channelName%>.disableDrag = true;

To invoke the menu:

<a href="javascript://" onClick="showMenu(window.<%=channelName%>);" title=" Click to view or modify channel options"><img src="<dt:scontent/>/enterprise/images/channel-button.gif" ></a>

Note –

In the above example, when you click an image, the pull down menu displays. You may have to delete the compiled JSP class cache under PortalServer-DataDir/portal/portal-ID/desktop/compiled directory to force recompilation of the changed JSPs.

Understanding Tabs

You can use tabs to categorize the information on your desktop. A tab is a web page. Each top level tab can have multiple nested tabs. The Enterprise Sample uses two tabs: Home and My Portal. The Home page has the nested tabs News and Career.

Every page is either one of the following:

ASCTabContainer: The framework that displays tabs. It can hold nested tabs.
ASCTableContainer: The framework that displays the rows and columns for a particular tab.

Before you can display the information within a channel, a tab and table container must be defined.

The Adventure Sports Cafe home page is a tab, and the News tab is nested within. A tab may specify a set of providers and/or portlets that it may contain. The home page consists of a type of table container which has a three column layout (thin, wide, thin).

Categorizing Content Using Tabs

The following procedures illustrate how to create and display information:

Creating a New Top-level Tab

To Create a New Top-level Tab

This procedure creates a new tab container by the name MyTabContainer and adds it to the list of Containers on the Portal Desktop administration page.

Steps

Click the Portals tab and click Portal-ID in the list of portals.

Select Enterprise Sample in the drop down list for Current Location.

Click the Manage Containers & Channels link.

In the left side frame, select ASCTabContainer in the View Type drop down list.

Select New Channel or Container link in the right side frame.

A popup window displays with a wizard to guide you through the steps for creating a new container.
1. Ensure that the correct values are selected for the portal and DN in the popup window. Select the Container radio button and click Next.
  
  A message displays indicating successful creation of the container.
2. Select ASCTabContainerProvider from the Container Provider drop down list and click Next.
3. Provide a unique name for the container. For example, MyTabContainer.
4. Verify the information and click Close.
  
  A message displays indicating successful creation of the container.

Select the link Show or Hide Channels and Containers on Portal Desktop link.

Ensure that the newly created container is listed in the list of containers Visible on the Portal Desktop list.

Verify the information and click Close to the Portal management page.

Changing Tab Properties

To Change Tab Properties

Steps

Click MyTabContainer under ASCTabContainer.

Change the description and title to My Top Level Tab and MyTab respectively in the Edit properties form.

Click Save to save the changes and return to the Portal administration page.

The newly created tab, MyTab, has no content. To add content to this tab, add another nested tab to MyTab.

Creating a Nested Tab

To Create a Nested Tab

The nested tab is an aggregation of channels, so it is created as a JSPTableContainerProvider.

Steps

Click the Portals tab and click on My Portal in the list of portals.

In the drop down list for Current Location select Enterprise Sample.

Click the Manage Containers & Channels link.

In the left side frame, select ASCTabContainer/MyTabContainer in the View Type drop down list.

In the right side frame, Click on New Tab to launch the tab creation wizard.

In the pop up wizard window, do the following.
1. Ensure that the values selected for Portal and DN are correct and click Next.
2. Specify the properties for the new tab. The Tab Name property value has to be unique across all containers. Leave the Removable property as selected, and click Next.
3. Ensure that the {Parent Tab Container value is set to ASCTabContainer/MyTabContainer. Select the appropriate radio button for Would you like to add content to the new tab? and click Next.
  
  If you opted to add content to the new tab, select channels to be displayed on the tab from the list of channels. Multiple channels (e.g., SampleXML) can be selected. Ensure that the Visible on Users Desktop option is selected.
4. Verify that you have entered the correct information and click Next.

Click Finish.

Displaying Content Using Layout Properties

You ca n change the layout of columns by modifying their layout properties. The layout of the columns is determined by a numeric value you assign for each table container. Every channel can be assigned a thickness: thin or wide. All the thin and wide channels are then aggregated by the containers and displayed according to the selected channel layout.

Changing the Width and Number of Columns

The numeric value for the layout is unique and is used as the value for the layout property of the container. Table 3–1 shows the numeric values associated with the number of columns and their widths.

Table 3–1 Column Layout


Layout	Number of Columns	Numeric value
Thin - Wide	Two	1
Wide - Thin	Two	2
Thin - Wide - Thin	Three	3

The default layout of the NewsContainer is Thin - Wide - Thin. The Enterprise Sample defines column widths as layout=3 (Thin-Wide-Thin). To extend support for more layouts, refer to Adding New Layouts.

To Change the Width and Number of Columns of a Nested Tab

Steps

Click the Portals tab and click on the portal-ID in the list of portals.

Select Enterprise Sample from the drop down list for Current Location.

Click the Manage Containers & Channels link.

Select NewsContainer in the left side frame.

Change layout property to a new numeric value (refer to layout table for valid values).

Click Save to save the changes.

To Verify that the Layout Properties Are Changed

Steps

Access the Enterprise Sample anonymous portal.

Adding New Layouts

The Enterprise Sample relies on the CSS file for positioning of channels on the page. When creating new layouts or modifying existing layouts, review the Enterprise Sample CSS files under /var/opt/SUNWportal/portals/portal-ID/web-src/enterprise/css.

The various CSS file are available and are selected based on client browser type and client operating system. The CSS file selection logic can be found in writeCSS function in /var/opt/SUNWportal/portals/portal-ID/web-src/enterprise/js/util.js.

To Add New Layouts

The Enterprise Sample supports layout=3 (THIN-WIDE-THIN) layout.

You can extend the code to support multiple layouts by modifying the file /var/opt/SUNWportal/portals/portal-ID/desktop/enterprise_sample/JSPTableContainerProvider/table.jsp.

Step

Replace the code in the table.jsp Listing 1 with the code in Listing 2.

Listing 1

<!-- Begin Left Column of Channels -->
<div class="tableContainerColumnLeft">
<dttable:getColumns id="channels" column="left" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="center"/>
</jsp:include>
</div>
<!-- End Left Column of Channels -->

<!-- Begin Middle Column of Channels -->
<div class="tableContainerColumnCenter"">
<dttable:getColumns id="channels" column="center" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="center"/>
</jsp:include>
</div>
<!-- End Middle Column of Channels -->

<!-- Begin Right Column of Channels -->
<div class="tableContainerColumnRight">
<dttable:getColumns id="channels" column="right" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="center"/>
</jsp:include>
</div>
<!-- End Right Column of Channels -->

Listing 2

You can find the original code in /var/opt/SUNWportal/portals/portal-ID/desktop/enterprise_sample/JSPTableContainerProvider/table.jsp starting at Line # 78

<dtpc:getIntegerProperty key="layout" id="layout"/>
<jx:declare id="layout" type="Integer"/>

<!-- start table-container -->
<% if (layout == 1) { %>
<!-- THIN-WIDE layout -->
<!-- Begin Left Column of Channels -->
<div class="tableContainerColumnLeft">
<dttable:getColumns id="channels" column="left" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="left"/>
</jsp:include>
</div>
<!-- End Left Column of Channels -->

<!-- Begin Right Column of Channels -->
<div class="tableContainerColumnCenter">
<dttable:getColumns id="channels" column="right" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="center"/>
</jsp:include>
</div>
<!-- End Right Column of Channels -->

<% } else if (layout == 3) { %>
<!-- THIN-WIDE-THIN layout -->
<!-- Begin Left Column of Channels -->
<div class="tableContainerColumnLeft">
<dttable:getColumns id="channels" column="left" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="left"/>
</jsp:include>
</div>
<!-- End Left Column of Channels -->

<!-- Begin Middle Column of Channels -->
<div class="tableContainerColumnCenter">
<dttable:getColumns id="channels" column="center" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="center"/>
</jsp:include>
</div>

<!-- Begin Right Column of Channels -->
<div class="tableContainerColumnRight">
<dttable:getColumns id="channels" column="right" scope="request"/>
<jsp:include page="column.jsp" flush="true">
<jsp:param name="columnName" value="right"/>
</jsp:include>
</div>
<!-- Begin Right Column of Channels -->

<% } else if (layout == 4) { %>
<!-- Add custom layout here -->
<% } %>
</div><!-- end table-container -->

Redeploy the portal web application using the utility: /opt/SUNWportal/bin/psadmin redeploy adminuser amAdmin -passwordfile password-filename -portal portal-ID.

Creating a Wiki Container and Channel

This section helps you to create a create a subtab title “My Wiki” under the My Portal tab with a wiki channel. The portlet is available to the employees of your organization and they can start collaborating via the wiki features.

The following procedures are described in this section:

To Create a Wiki Container

Steps

Click the Portals tab.

Click the portal-ID in the Portals list.

Select Enterprise Sample [Org] in the Select DN list.

Click Manage Containers and Channels.

Click MyPortalContainer under ASCTabContainer.

Click New Channel or Container in the MyPortalContainer Task and Properties page.

In the New Channel or Container wizard, specify the following:
1. Select Portal: portal-ID
2. Select DN: Enterprise Sample [Org]
3. Type Container.
4. Container Provider: DynamicAggregationContainerProvider
5. Channel or Container Name: WikiContainer
  
  The Container is now available for use

To Edit the Wiki Container Properties

Steps

Click WikiContainer under MyPortal Container.

In the WikiContainer tasks and properties page, modify the desired property values.

For example you might want to change the channel title to My Wiki.

Click Save.

To Create the Wiki Channel

Steps

Click WikiContainer under MyPortalContainer.

Click New Channel or Container In the WikiContainer Tasks and Properties page.

In the New Channel or Container wizard, specify the following:
1. Select Portal: portal-ID.
2. Select DN: Enterprise Sample [Org].
3. Type: Channel.
4. Channel Type: JSR 168 Portlet Channel.
5. Portlet: wiki.WikiPortlet.
6. Channel or Container Name: Wiki
  
  The Enterprise Sample now has a new subtab “My Wiki” under the My Portal tab that contains the wiki channel.