test

Deployment Example: Deploying and Customizing the Documentum Portlet

Chapter 7 Creating and Customizing Portlets

If you are writing portlets to run within a JSR-168 compliant portal application server, you need to follow the guidelines outlined in the following topics:

For information on adding preferences to a portlet, refer to Chapter 3, Environment Configuration. For information on how to add help for a portlet, refer to Adding portlet help.

Documentum Portlet Class

Documentum portlets use a single portlet class, com.documentum.web.env.jsr168.DocumentumComponent which extends javax.portlet.GenericPortlet. This class will launch the component that you specify for the portlet as the value of the view mode in the portlet.xml file and will also provide access to preferences and help for the component using the preferences and help mode values in the portlet.xml file.

Caution – Caution –

If your IDE creates portlets by creating the portlet class, make sure you do not create a Documentum portlet within the IDE by specifying the portlet class as DocumentumComponent. The IDE will overwrite the Documentum portlet class and render all Documentum portlets invalid. If this happens, you can restore the portlet class from your installation WAR file.

Portlet User interface

JSP pages in portlets should contain HTML fragments only. The portlet contributes its content to a larger page, so it cannot be a fully formed HTML page. Use the tags <dmf:html>, <dmf:head>, and <dmf:body> instead of <HTML>, <HEAD>, <TITLE>, or <BODY> elements. These tags will be rendered appropriately for portal environments. They enable icon rendition and error handling, so they should not be omitted from JSP pages that are used in portlets.

Your portlet content will probably be contained within a table cell (<TD>) on the portal page. You can use default width and height and add width and height preferences to your portlet XML configuration. The portlet will then use scroll bars if the content is too large for the available table space. Avoid unnecessary layout elements to reduce the amount of scrolling needed for your portlet.

Tip –

Avoid placing <nobr> tags around table cells to prevent line breaks. This will cause your portlet to push the portal page wide and may force excessive scrolling when users view other portlets. To allow portal users with disabilities to be able to use your portlet, the JSPs should be fully enabled for keyboard-only control and other assistive technologies. For guidelines on making your portlet components accessible, refer to Web Development Kit and Client Applications Reference Guide.

In general, you should minimize the use of iFrames and JavaScript in your portlets, because support differs between browsers and versions. Do not use popup browser instances, which will cause the portal to lose track of the current portlet's state and history. Some portals provide a widget on the titlebar that allows the user to pop the portlet up as a new browser window.

Use Java comments rather than HTML comments (<! - comment ->) in your files. HTML comments are rendered into the output even though they are not visible, increasing the document size and download time. Java comments similar to the following example are removed from the rendered source along with Java code:


<% //this is a comment %>
Tip –

Give each control in your portlet components a unique name, because they will be rendered by the portal container into a single HTML page.

Portal Styles

Your portlet should use portal style classes that are defined in the portal's cascading style sheet. Consult your portal documentation for instructions on setting portlet styles. In the following example from a portlet JSP page, an input element uses a portal style class called portlet-form-input-field:


<input class="portlet-form-input-field" type="submit">

The .css file is loaded by the portal and should not be reloaded by a portlet. For class definitions and associated values, refer to the JSR-168 specification. This interface converts a WDK standard CSS style into one of the portal styles. By default, this interface returns the WDK style unchanged. Implement the method mapCssClass() to perform the mapping. This method has the following signature:


public String mapCssClass (String strCssClass)

Where strCssClass is the WDK CSS class name. Returns the mapped portal style. You can add a branding image to brand your portlets, replacing the Documentum logo image in the lower right-hand corner of the portlet rendition. To do this, locate the path to an image within your portal directories and enter it as the value of the BrandingImage key in the Environment.properties file for your portal. For example, the file for the SUN portal is named SunPortalEnvironment.properties, and it is located in /WEB-INF/classes/com/documentum/web/env/sun directory. A custom image placed in /custom/images is registered as follows:


BrandingImage=/custom/logos/myproduct.gif

This image is rendered after the portal is restarted, similar to the following. The image launches the About component which can be customized to describe your application.

Namespace in Portlets

The JSR-168 specification for portal servers specifies that the URIs, element name attributes, and JavaScipt methods should be encoded with the namespace of that portlet. Use the IRender method namespaceElement(strPortletInstanceName) to encode these elements. In the following example, a form element is encoded for portal PC_202:


<% IRender render = EnvironmentService.getEnvironment().getRenderContract();%>
<FORM method=POST name="<%=render.namespaceElement("form1")%>" action="">

The form element will then be rendered as follows:


<FORM method=POST name="PC_202_form1" action="">

To encode JavaScript with the portal namespace, WDK provides a servlet and VirtualJS. This servlet rewrites static JavaScript files to portlet-specific versions, changing method names and any form variable names that are used to the appropriate portal-specific namespace. The servlet is used by tag rewrite methods in a portal environment, so that the tags no longer point to static JavaScript files but to dynamic versions hosted by the servlet. For example, the following JavaScript declaration in a WDK page:


<script src="/wdk/wdk/include/events.js" language="javascript1.2">
</script>

is rewritten to:


<script src="/wdk/virtualjs/PC_202/wdk/include/events.js"
language="javascript1.2">
</script>

The servlet delegates the rewriting of JavaScript files to Java classes that implement the IJavaScriptHandler interface. JavaScript files that must be rewritten are registered for a particular handler class by adding entries into the VirtualJS.properties file located in /WEB- INF/classes/com/documentum/web/env directory.

Portlet Refresh

You can enable a refresh link in your portlet UI by implementing an onRefreshData() method in your portlet component class. You must then register your portlet in PortalEnvironment.properties file located in WEB-INF/classes/com/documentum/web/env directory

A refresh link will be generated for your portlet.

Note –

The inherited onRefreshData() method is not sufficient to generate a Refresh link. Your component class must explicitly override onRefreshData().

Example 7–1 Refreshing data in a portlet component

The following example from the MyObjects class refreshes data when the user clicks on the Refresh link.


public void onRefreshData()
{
	super.onRefreshData();
	readConfig();
	updateControl();
	// force refresh on dataproviders
	((Datagrid)getControl(
	MYOBJECTS_GRID, Datagrid.class)).getDataProvider().refresh();
}

Adding Portlet Help

You can amend the help that is installed by WDK for Portlets in your portal application and add new help files for your custom portlet components.

When you add a new portlet to portlet.xml file, add a value for the help mode preference. For example, for the portlet DocumentumDrilldown, the help mode is set to the value cabinets:


<preference>
	<name>help</name>
	<value>cabinets</value>
</preference>

This help value maps to an HTML file that must be located in /app_root_directory/language_code/cabinets directory, for example, /PORTAL_APP_HOME/help/en/DocumentumPortlets/cabinets/default.htm.