Web Development Kit for Portlets Development Guide · PDF fileportlet.AportletthatdispatchesaWDKcomponentmustspecifyitsportletclassas ... isrewrittento:

Web Development Kit for PortletsDevelopment Guide

Version: 5.3 SP1September 2005

Copyright © 1994-2005 EMC Corporation. All rights reserved.

Table of Contents

Preface ........................................................................................................................... 9

Part 1 Web Development Kit for Portlets ................................................................. 13

Chapter 1 Introduction And Overview .................................................................... 15WDK foundation technologies..................................................................... 15The Documentum web architectural stack .................................................... 16Documentum Content Server .................................................................. 18J2EE Application or Portal Server............................................................. 18Service Layer.......................................................................................... 18The WDK Environment Layer ................................................................. 19Presentation Model................................................................................. 19Component Model.................................................................................. 20Application Model.................................................................................. 21

What is JSR 168? ......................................................................................... 21What is a Documentum Portlet? .................................................................. 22Portlet files ............................................................................................. 22WDK for Portlets architecture.................................................................. 23

Chapter 2 Creating Documentum Portlets ............................................................. 27Documentum portlet class........................................................................... 27Portlet user interface ................................................................................... 28Portal styles................................................................................................ 28Namespace in portlets ................................................................................ 29Portlet refresh............................................................................................. 30Adding portlet help .................................................................................... 30

Chapter 3 Portlet Authentication ........................................................................... 33Manual authentication ................................................................................ 33User principal authentication ...................................................................... 34Ticketed Login ........................................................................................... 36Saved credentials authentication.................................................................. 38Single sign-on............................................................................................. 38Skip authentication ..................................................................................... 39Login preferences ....................................................................................... 39Login locale................................................................................................ 40Number of user sessions ............................................................................. 40

Chapter 4 Troubleshooting .................................................................................... 41Tracing ...................................................................................................... 41

Web Development Kit for Portlets Development Guide 3

Table of Contents

Chapter 5 Integrating with Portal Environments .................................................... 43Where to integrate WDK into a portal .......................................................... 43Environment classes ................................................................................... 44AbstractEnvironment class...................................................................... 46Environment class .................................................................................. 47AppServerEnvironment class .................................................................. 48PortalEnvironment class ......................................................................... 48Jsr168Environment class ......................................................................... 48BeaPortalEnvironment class .................................................................... 49IbmPortalEnvironment class.................................................................... 50SunPortalEnvironment class.................................................................... 50StandaloneJsr168Environment class ......................................................... 51

Environment configuration ......................................................................... 51Environment APIs ...................................................................................... 51ISuperCredentials................................................................................... 52ILogin.................................................................................................... 52ISecurity ................................................................................................ 52IPreference (reading and writing preferences) .......................................... 53Reading user-level preferences ............................................................ 54Writing user-level preferences ............................................................. 57Preference mapping............................................................................ 58Preference scopes ............................................................................... 58

IRender.................................................................................................. 59ITag ....................................................................................................... 60IJavascriptHandler.................................................................................. 60ITheme .................................................................................................. 61ILocale ................................................................................................... 61ILifecycle ............................................................................................... 61ISession ................................................................................................. 62IContentTransfer .................................................................................... 62IMessageService ..................................................................................... 63IError..................................................................................................... 63IInfo ...................................................................................................... 63

Registering an environment ........................................................................ 64HTML post-processing ............................................................................... 65Tag class ................................................................................................ 66Attribute class ........................................................................................ 66Post-processing example ......................................................................... 66

Environment hooks .................................................................................... 68

Chapter 6 Customization Overview ....................................................................... 69The custom layer ........................................................................................ 69Custom layer definition inheritances and overrides................................... 70

What to customize ...................................................................................... 71Applications........................................................................................... 72Components........................................................................................... 72How to determine a component from the user interface ........................ 73Listing the application’s components.................................................... 74Determining which parts of the component to customize ...................... 74

Actions .................................................................................................. 75Controls................................................................................................. 75JSP Pages (forms).................................................................................... 75Events.................................................................................................... 75Branding................................................................................................ 76Text strings ............................................................................................ 76

4 Web Development Kit for Portlets Development Guide

Table of Contents

Customization process ................................................................................ 76Customization guidelines........................................................................ 76

Part 2 Customization Examples ............................................................................... 79

Chapter 7 Linking To A Documentum Component ................................................. 81

Chapter 8 Converting The DQL Editor Component To A Portlet ............................ 85

Chapter 9 Creating A Simple Time Sheet ............................................................... 89Creating the time sheet portlet definition ..................................................... 89Creating the time sheet component definition............................................... 90Creating the time sheet UI (JSP page)........................................................... 90Creating the time sheet classes..................................................................... 91Timesheet class....................................................................................... 91TimesheetForm class............................................................................... 92

Chapter 10 Creating A Custom Type Object Grid .................................................... 95

Chapter 11 Adding A Logout Portlet ...................................................................... 105

Part 3 Portlet Reference ......................................................................................... 109

Chapter 12 Portlet Specic Components ............................................................... 111Portlet specific components ....................................................................... 111portallogin ........................................................................................... 111Parameters ........................................................................................... 111Elements .............................................................................................. 112

Chapter 13 Actions In A Portal Environment ......................................................... 113Amending actions using action definition files............................................ 113dm_smart_list_actions.xml ........................................................................ 113generic_actions.xml .................................................................................. 114room_actions.xml ..................................................................................... 114Disabling actions using JSP files................................................................. 114


Table of Contents

List of Figures

Figure 1–1. DocumentumWeb Architectural Stack............................................................. 17Figure 1–2. WDK for Portlets Architecture......................................................................... 24Figure 5–1. Environment class inheritance diagram............................................................ 45Figure 7–1. Link to a Documentum component.................................................................. 82Figure 7–2. Linking back to the Portal ............................................................................... 83Figure 8–1. Component converted to portlet ...................................................................... 87Figure 9–1. Simple time sheet portlet................................................................................. 93Figure 10–1. Custom type object grid ................................................................................. 95Figure 11–1. Logout portlet before logout......................................................................... 108Figure 11–2. Logout portlet after logout ........................................................................... 108


Table of Contents

List of Tables

Table 6–1. Structure of the custom layer ........................................................................... 70


Table of Contents


Preface

This guide is divided into three parts:

• Part I describes how to configure and customize Documentum portlets• Part II contains some customization examples• Part III describes the reference information for the portletsThe following references are available on the Documentum product download site:• Web Development Kit Development Guide• Web Development Kit and Client Applications Reference Guide• Web Development Kit and Applications Tutorial• WDK and DFC javadocsCheck the Documentum technical support Web site (support.documentum.com) for revisions of thedocumentation. Click the Documentation link to search for documents related to your installedversion of WDK or WDK client application. The support site also provides peer support forumsthat are monitored by technical support experts.

The Documentum developerWeb site, developer.documentum.com, provides sample code, tips, whitepapers, and a wealth of information to assist you in developing Documentum-enabled applications.

Intended audienceThis manual is intended for two audiences:• Java developers who are developing custom JSP-based Web standalone and portal

applications that incorporate Documentum functionality• Web page designers who are configuring WDK client applicationsTo configure WDK-based applications, you must be familiar with the followingtechnologies:• JSP 1.1 including tag libraries• Cascading style sheets (CSS)• HTML, particularly forms, tables, and framesets• JavaScript, including client events and event handling, frame referencing, and form

action methods• XML


http://support.documentum.com

http://developer.documentum.com

Preface

To customize WDK-based applications, you must be familiar with the above-mentionedtechnologies and the following additional languages and standards:• Java 1.3.1 or 1.4• Servlet 2.3• Sun JSR-168 standard for portlets

TerminologyAPP_HOME is the root directory of the Documentum Web application or portalapplication in your installation. The paths for control, action, and component files areshown relative to this base location.

This guide uses the following conventions:

Convention Description

Italics Represents a variable name for which you mustprovide a value, or a defined term

typewriterRepresents code samples, commands, user input,and computer output

{curly braces} Indicates a Java or CSS code implementation

<XXX> Represents an XML element or JSP tag as it appearsin an XML or JSP file. End tags are not alwaysincluded in examples, unless the element is closed,for example, <dmf:webform/>.

notdefined=”true” All values for control and action attributes orcomponent parameters are passed as strings, eventhough some are treated as boolean values by thecontrol, action, or component class. For example,true and false are treated as booleans.

<nlsid>MSG_XXX</nlsid> If you provide National Language Support (NLS),enclose the value keys in <nlsid> and </nlsid>tags. The WDK locale service will replace thevalue with the corresponding lookup value in theappropriate localized resource file. The user’s localewill determine which localized version of the stringis used.


Preface

Documentation resourcesThe Documentum Web Development Kit contains documentation and source files toassist you in developing custom Web applications:• Web Development Kit Development Guide

Contains general configuration, customization, and application-building informationfor application developers.

• Web Development Kit and Client Applications Reference Guide

Contains information about all of the configurable settings for controls, actions,and components in WDK.

• Web Development Kit and Applications Tutorial

Contains several tutorials on configuring and customizing WDK.• Web Development Kit and Applications Installation Guide

Describes how to prepare for, install, and deploy WDK and custom WDK-basedapplications.

• WDK for Portlets Installation Guide

Describes how to prepare for, install, and deploy WDK for Portlets.• Documentum 5 System Migration Guide

Describes how to migrate WDK 4 and RightSite based applications to WDK 5. (Partof the Documentum 5 system documentation set.)

• Source files for basic WDK controls and samples are installed in /wdk/src.Source files for all webcomponent layer components and actions are installed in/webcomponent/src.

• The Documentum CustomerNet Web site, support.documentum.com

Provides WDK and client applications support forums, developer tips andcomponent library, sample code, white papers, and a wealth of information to assistyou in developing Documentum-enabled applications.


http://support.documentum.com

Preface

Revision historyThe following changes have been made to this document:

Revision History

Revision Date Description

September 2005 Initial document release for 5.3 SP1.


Part 1

Web Development Kit for Portlets

The Documentum portlets installer installs WDK runtime, portlets, and componentsin a JSR-168 compliant portal server. The WDK runtime for WDK for Portlets differssomewhat from the runtime for standalone Web applications, but these differences arenot exposed to customizations.

The installation guide for Documentum portlets provides information on installingWDK for Portlets and runtime into your portal. This part of the documentation notes theadditional WDK framework and portlets for the portal environment.

The configuration and customization guidelines for portal and standalone Webenvironments are the same. For application-level configuration information, refer to theWeb Development Kit Development Guide. For control, action, and component configurationguidelines, refer to theWeb Development Kit and Client Applications Reference Guide. Forportlet specific reference information, refer to Part III of this guide.

The following topics describe WDK for Portlets:• Chapter 1, Introduction And Overview• Chapter 2, Creating Documentum Portlets• Chapter 3, Portlet Authentication• Chapter 4, Troubleshooting• Chapter 5, Integrating with Portal Environments• Chapter 6, Customization OverviewYou can create components that work in both portal and standalone environments.Launch the appropriate type of component for a portal or standalone Web applicationby using the LaunchComponent action class with a dynamic filter. For informationon dynamic filters, refer to “Dynamic Component Launching” inWeb Development KitDevelopment Guide.


Web Development Kit for Portlets


Chapter 1Introduction And Overview

The Documentum Web Development Kit (WDK) is a Web application tool set. WDK provides thefollowing functionality:• A Java tag library of easily configured Web-based UI widgets• A Java framework that supports application-server based state management, messaging,

branding, history, internationalization, and content transfer• A set of configurable components that generate HTML widgets and provide access to repository

functionalityWDK’s architecture incorporates three models: A presentation model that uses JSP tag librariesto separate Web page design from behavior, a component model that encapsulates repositoryfunctionality in configurable server-side components, and an application model that consists of a setof components and the WDK application framework, DFC, and native libraries.

This introduction to WDK includes the following topics:• WDK foundation technologies, page 15• The Documentum web architectural stack, page 16• What is JSR 168?, page 21• What is a Documentum Portlet?, page 22

WDK foundation technologiesThe WDK programming model is based the following technologies:

• XML configuration

Components and actions in WDK are configured through XML configuration files.The WDK configuration service reads configuration elements, both WDK-suppliedand user-defined. Configuration files make it easy to change the behavior ofcomponents, actions, and applications through simple text editing.

• JSP 1.1


Introduction And Overview

A JSP page is a text file that describes how to process an HTTP request to createan HTML response. A JSP page in WDK consists of fixed (template) HTML anddynamic content rendered by JSP tags, expression, and scripting. Most of the UI isgenerated by JSP tags that can be configured on the JSP page. JSP pages are compiledinto servlets (Java classes) by the JSP container or by a third-party compiler. Theseservlets execute on the server when a JSP page is requested. The servlet performs aserver task or generates dynamic content that is then displayed on the client browser.

• Servlet 2.3

A Web application runs in a J2EE-compliant JSP container, which provides the JavaRuntime Environment (JRE) and, usually, the JSP translator (compiler). Each JSPpage is translated into a servlet class and instantiated every time the JSP page isrequested. Additional WDK servlets provide back-end support for timeout, contenttransfer, and virtual link redirection.

• J2EE security

If you set up J2EE security in your J2EE server, you can configure WDK to supportsingle login. The Java authentication mechanism is used to support sign-on to boththe Web server and the repository. Manual authentication, which has been used forprevious versions of Documentum clients, is also supported.

The Documentum web architectural stackThe Documentum Web stack is illustrated below. The layers in the stack are describedin order, starting from the bottom layer.



Figure 1-1. Documentum Web Architectural Stack

The application stack is described in the following topics:Documentum Content Server, page 18J2EE Application or Portal Server, page 18Service Layer, page 18The WDK Environment Layer, page 19Presentation Model, page 19



Component Model, page 20Application Model, page 21

Documentum Content Server

The Web architecture stack has at its base the Documentum Content Server. All ofthe WDK services and programming model exist to expose the content managementfunctionality of the Content Server.

J2EE Application or Portal Server

The J2EE server provides an application environment for WDK or other J2EEapplications. A J2EE application server and requires a certified version of the J2SE(standard edition) SDK and the J2EE SDK. For certified versions of the Java environment,see the WDK release notes.

A portal server that is JSR 168 compliant provides a standard portal environment inwhich WDK portal components can run.

A non-JSR 168 compliant portal server also provides a portal environment that can runWDK portal components using WDK environment APIs.

Service Layer

The Java environment, DFC, and JDBC connectors provide the following services:

• I18N

The framework provides internationalization support for externalized stringsthat can be localized or changed for your application. The Java SDK managesinternationalized resources.

• Data access

The DFC session interface and JDBC connectors provide data access.• Authentication

The framework supports a pluggable authentication scheme and is prepackagedwith several schemes: J2EE Principal authentication, manual authentication, singlesign-on (SSO, unsupported), and ticketed login. Skip authentication allows acomponent to bypass authentication if the component does not require a session.

• Business Object Framework (BOF)



The DFC BOF places business logic in reusable components.• Session pooling

The dmcl.ini file on the WDK host can be configured as a client for serverconnection pooling. WDK applications take advantage of session pooling, increasingperformance over non-pooled sessions.

The WDK Environment Layer

The environment layer in the WDK framework provides a means of supporting varioustypes of Web application environments:• Standalone Web application, such as Webtop, Documentum Administrator, Digital

Asset Manager, or Web Publisher• JSR 168 compliant portal environments:

— BEA portal (integration supplied by Documentum)

— IBM portal (integration supplied by Documentum)

— Other JSR 168 compliant portals• Non JSR 168 compliant portal environments

Presentation Model

The presentation model consists of JSP tag libraries and HTML in JSP pages as wellas a server-side presentation framework.

The Documentum JSP tags generate HTML widgets and databound tables, lists, andother presentation scripting to the browser. Server-side control classes provide access tothe control tags and maintain state on the server. A form processor maintains the HTMLform state and lifecycle, which is not possible with standard HTML forms.

In addition to the control tags and server-side control classes, the presentation modelincorporates the following services:• Form processor, which interprets HTTP requests and translates requests into WDK

method calls and events• History mechanism, which maintains browser history and navigation• Configuration service, which looks up configuration contracts for actions and

components and dispatches the appropriate UI for the user’s context• Branding service, which manages the look and feel for the application• Locale service, which delivers a localized UI



• Help service, which delivers localized, context-sensitive help• Message service, which displays localized messages to the user

Component Model

The component model provides a configurable, encapsulated set of Documentumfunctions or components. A component is composed of one or more JSP pages, supportingbehavior classes, and an XML configuration file. Component JSP pages use WDKcontrols and actions from the tag libraries, and each component handles control eventswith its own event handlers.

The WDK framework enforces a contract for each component, consisting of parametersthat initialize the component. The component behavior class includes event handlersthat respond to user action and properties that get and set the state of a component.

The component contract is defined in an XML component configuration file. Thecomponent is defined within <component></component> elements in the file. In additionto contract parameters, the definition includes a component behavior class, an NLSproperties resource bundle, a help context ID, and, sometimes, additional configurationelements. A component can include other components, acting as a container.

The component dispatcher dispatches a particular component dynamically on thefollowing criteria:

• Calling context

Context consists of runtime conditions such as object type, current component, oruser role. For example, one component definition is called when the selected objectis a folder, and another component definition is called when the selected object isa document.

• Component implementation

Several types of component implementation are supported, such as WDK 4.2, rawJSP pages, WDK 5, or other as specified in the component XML file. For example, ifthe component definition specifies that it is a WDK 4.2 component, the componentis dispatched using the 4.2 framework. If the component is a raw JSP page, thecomponent is dispatched using the J2EE server framework without calling the WDK5 framework.

Components are often launched by actions. Actions launch components through UIwidgets such as menu items or links. An action can evaluate preconditions to ensure thatthe action is valid for the user’s context.



Application Model

A Documentum Web application consists of a set of components and the WDKapplication framework, DFC, and native libraries. The WDK application frameworkconsists of services that apply across the application, such as the configuration, action,messaging, branding, and tracing services.

Documentum’s WDK based components are designed for integrations in the followingapplication environments:• Application server

An environment for running JSPs, Servlets and EJBs. Documentum’s Webtopapplication is built for this environment. Services such as authentication andconfiguration are provided by the WDK framework.

• Portal server

An environment for running portlets, JSP pages, and servlets. Services such asauthentication and configuration are provided by the portal server.

A Web application can contain several application layers. The application modelenforces consistent appearance and behavior across all application layers containedwithin the root WDK-based application. The J2EE-compliant root context can containapplication layers that inherit application parameters from other application layers. Forexample, the base application layer is WDK. The WDK application layer is extended bythe webcomponent application layer. Your custom application layer can then extend thewebcomponent application layer.

Using branding, an application layer can supply themes that provide your application’sunique appearance through icons, images, and style sheets.

What is JSR 168?The Sun Java Specification Request (JSR) 168 was created to promote portability ofportlets to different portals. This will be particularly important when a portlet is availableas a Web service, following the Web Services for Remote Portals (WSRP) protocol.

The JSR 168 specification establishes a standard API for creating portlets, which provideapplication logic through a portal. The specification defines a set of APIs for portlets andaddresses standardization for the following aspects of a portlet:• Portlet interface• Portlet configuration• Preferences• User information retrieval (user information persistence is portal-specific)



• Portlet requests and responses• Deployment packaging• Security

What is a Documentum Portlet?Based on the Sun portlet specification JSR-168, a portlet is a Java-based web component,managed by a portlet container, that processes requests and generates dynamic content.Portlets are used by portals as pluggable user interface components that provide apresentation layer to Information Systems.

WDK for Portlets installs Documentum portlets, WDK run time, and WDKcomponents into a portal Web application in a certified portal server. A singleportlet class, DocumentumComponent, dispatches WDK components for eachportlet. A portlet that dispatches a WDK component must specify its portlet class ascom.documentum.web.env.jsr168.DocumentumComponent.

The components that are dispatched for portlet view and edit modes are specified foreach portlet in portlet.xml. The context-sensitive portlet help file is dispatched to a newbrowser window based on the value of the help mode in portlet.xml.

Caution: If your IDE creates portlets by creating the portlet class, make sure you do notcreate a Documentum portlet specifying the portlet class as DocumentumComponent.The IDE will overwrite the Documentum portlet class and render all Documentumportlets invalid. If this happens, you can restore the portlet class from your installationwar file.

The following topics describe Documentum portlets:Portlet files, page 22WDK for Portlets architecture, page 23

Portlet les

WDK for Portlets installs the following portlets and supporting files:• /custom

Top Documentum portlet application layer. Use this directory for your customportlet files

• /help

Contains localized help files for portlets



• /portlets

Contains portal-specific files as required by the portal vendor• /wdk

Contains WDK components and supporting files• /webcomponent

Extends the /wdk layer and defines more components• /WEB-INF/portlet.xml

Contains definitions for all JSR-168 compliant portlets including Documentumportlets

• /WEB-INF/classes

Contains Documentum and custom classes for portlet components• /WEB-INF/lib

Contains Documentum jar files• /WEB-INF/tlds

Contains Documentum tag libraries• /DOCUMENTUM_HOME

DFC is installed to this directory. The directory is selected during installation. IfDocumentum products have already been installed on the host, the pre-existinghome directory is used.

WDK for Portlets architecture

In the diagram below of a Documentum portal application, an environment layer isshown. This layer is conceptual only and does not represent an actual applicationlayer like wdk or webcomponent. The environment layer consists of all of the parts ofa Web application that differ depending on whether the application is a standaloneWeb application or a portal application.



Figure 1-2. WDK for Portlets Architecture

The differences between the standalone and portal runtime elements in the environmentlayer are summarized below:• Error handler

IError defines methods for overriding errorPage <%@ page %> directive and fordisplaying errors inline.

• Lifecycle event handlers

ILifecycle allows the developer to hook into application lifecycle events to performinitialization or clean up.

• Locale

ILocale defines a set of methods for reading the Locale and TimeZone of the externalenvironment.

• Preferences

IPreference defines a set of methods for reading and writing preference values forcomponents, users, groups, or administrators.

• Rendering



IRender provides a set of methods for rewriting URL attributes in the WDKcomponent’s HTML response.

• Tag handlers

ITag allows the environment to specify how standard HTML tags should berendered.

• Themes

ITheme allows the external environment to convert a WDK CSS style into oneof its own styles.

See Environment APIs, page 51 for more information on these environment interfaces.




Chapter 2Creating Documentum Portlets

If you are writing portlets to run within a JSR-168 compliant portal application server, you need tofollow the guidelines outlined in the following topics:• Documentum portlet class, page 27• Portlet user interface, page 28• Portal styles, page 28• Namespace in portlets, page 29• Portlet refresh, page 30• Adding portlet help, page 30For information on adding preferences to a portlet, refer to Chapter 5, Integrating with PortalEnvironments.

For information on how to add help for a portlet, refer to Adding portlet help, page 30. For examplesof portlets, refer to Part 2.

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

Caution: If your IDE creates portlets by creating the portlet class, make sure you donot create a Documentum portlet within the IDE by specifying the portlet class asDocumentumComponent. The IDE will overwrite the Documentum portlet class andrender all Documentum portlets invalid. If this happens, you can restore the portlet classfrom your installation war file.


Creating Documentum Portlets

Portlet user interfaceJSP pages in portlets should contain HTML fragments only. The portlet contributesits 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 both portal andstandalone environments. They enable icon rendition and error handling, so they shouldnot be omitted from JSP pages that are used in portlets.

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

Tip: Avoid placing <nobr> tags around table cells to prevent line breaks. This will causeyour portlet to push the portal page wide and may force excessive scrolling when usersview other portlets.

To allow portal users with disabilities to be able to use your portlet, the JSPs should befully enabled for keyboard-only control and other assistive technologies. For guidelineson making your portlet components accessible, refer toWeb Development Kit and ClientApplications 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 browserinstances, which will cause the portal to lose track of the current portlet’s state andhistory. Some portals provide a widget on the titlebar that allows the user to pop theportlet up as a new browser window.

Use Java comments rather than HTML comments (<! – comment –>) in your files. HTMLcomments are rendered into the output even though they are not visible, increasing thedocument size and download time. Java comments similar to the following example areremoved 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 berendered by the portal container into a single HTML page.

Portal stylesYour portlet should use portal style classes that are defined in the portal’s cascading stylesheet. 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 styleclass called “portlet-form-input-field”:<input class="portlet-form-input-field" type="submit">

The .css is loaded by the portal and should not be reloaded by a portlet. For classdefinitions and associated values, refer to the JSR-168 specification.

If your component will be used by both portal and standalone applications, then usethe WDK style classes and the environment’s theme mapping interface ITheme. Thisinterface converts a WDK standard css style into one of the portal styles. By default, thisinterface returns the WDK style unchanged. Implement the method mapCssClass() toperform 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 Documentumlogo image in the lower right-hand corner of the portlet rendition. To do this, locatethe path to an image within your portal directories and enter it as the value of theBrandingImage key in the Environment.properties file for your portal. For example, thefile for the BEA WebLogic portal is named BeaPortalEnvironment.properties, and it islocated in /WEB-INF/classes/com/documentum/web/env/bea. 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 imagelaunches the About component, which can be customized to describe your application.

Namespace in portletsThe JSR-168 specification for portal servers specifies that the URIs, element nameattributes, and JavaScipt methods should be encoded with the namespace of that portlet.Use the IRender method namespaceElement(strPortletInstanceName) to encode theseelements. 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, VirtualJS. Thisservlet rewrites static JavaScript files to portlet-specific versions, changing method namesand 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 <include



src=" tags no longer point to static JavaScript files but to dynamic versions hosted by theservlet. 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 theIJavaScriptHandler interface. JavaScript files that must be rewritten are registered for aparticular handler class by adding entries into the VirtualJS.properties file, located in/WEB-INF/classes/com/documentum/web/env.

Portlet refreshYou 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 inPortalEnvironment.properties, located in WEB-INF/classes/com/documentum/web/env.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 2-1. Refreshing data in a portlet componentThe following example from the MyObjects class refreshes data when the user clickson the Refresh link:public void onRefreshData(){super.onRefreshData();readConfig();updateControl();// force refresh on dataproviders((Datagrid)getControl(MYOBJECTS_GRID, Datagrid.class)).getDataProvider().refresh();

}

Adding portlet helpYou can amend the help that is installed by WDK for Portlets in your portal applicationand add new help files for your custom portlet components.



When you add a new portlet to portlet.xml, add a value for the help mode preference.For example, for the portlet DocumentumDrilldown, the help mode is set to the valuecabinets:<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, for example, /PORTAL_APP_HOME/help/en/DocumentumPortlets/cabinets/default.htm.

If your component is used for both portal and standalone environments,make sure that the help button for the standalone environment help isnamed DialogContainer.CONTROL_HELPBUTTON. (You must importcom.documentum.web.formext.component.DialogContainer into your JSP page.) Helpbuttons with this name will be suppressed in portal environments so that portlet helpcan be launched instead. For example:<dmf:button name=’<%=DialogContainer.CONTROL_HELPBUTTON %>’ nlsid=’MSG_HELP’onclick=’onClickHelp’ runatclient=’true’ height=’16’ cssclass="buttonLink"imagefolder=’images/dialogbutton’ tooltipnlsid="MSG_HELP_TIP"/>




Chapter 3Portlet Authentication

Several types of login connections are available for portlets:• Manual authentication, page 33• User principal authentication, page 34• Ticketed Login, page 36• Saved credentials authentication, page 38• Single sign-on, page 38The following additional login topics are described inWeb Development Kit and Client ApplicationsReference Guide:

Skip authenticationSilent loginExplicit loginLogin preferencesLogin localeNumber of user sessions

If a portlet does not have a repository session, the dispatcher calls the authentication service,which attempts authentication using authentication schemes in the order specified in thecom.documentum.web.formext.session.AuthenticationSchemes. properties file. Place your preferredauthentication scheme first in this list. Schemes in the list must be numbered sequentially. If none ofthe authentication schemes succeed, the dispatcher calls and displays the login component.

In addition to the topics listed above, refer toWeb Development Kit and Client Applications ReferenceGuide for a description of the authentication configuration elements in app.xml.

Manual authenticationManual authentication occurs on the first access to a specific repository. The user ispresented with a login dialog upon request of a component that requires a session. Loginto a repository is handled by DocbaseLoginAuthenticationScheme.


Portlet Authentication

In a portal environment, a user must first authenticate against the Portal environmentvia the portal’s login page and then authenticate against each Content Server via aWDK login page.

After a successful Content Server connection, the user’s login information is stored inthe portal server’s preference store using the environment’s IPreference.writeString()method.

Note: Put DocbaseLoginAuthenticationScheme last in the list of authenticationschemes if you are supporting ticketed or user principal authentication. If theDocbaseLoginAuthentication scheme is first in the list, the login dialog will alwaysbe presented to the user.

User principal authenticationJ2EE principal-based authentication allows a single login to the portal server andContent Server. Each portal server has its own documented procedures for setting upserver-based authentication.

WDK supports server-authenticated users by means of a trusted authenticator credentialsfor each repository. The identity of the user who logs in to the Web application mustmatch the login identity in the repository. This identity (username) is then passed tothe Web application, but the user’s password is not passed. WDK then logs into therepository for the user by employing a trusted authenticator identity. The trustedauthenticator must be a superuser for the given repository.

Two user principal authentication schemes are available:• UserPrincipalAuthenticationScheme

Supports multi-repository authentication when more than one repository projects tothe connection broker that is used by the portlet container host

• SingleDocbasePerDocbrokerAuthenticationScheme

Supports login to a single repository when only one repository projects to theconnection broker that is used by the portlet container host

To set up J2EE principal authentication:

1. Make sure at least one of the J2EE principal authentication schemesabove is listed first in the list of authentication schemes in the filecom.documentum.web.formext.session.AuthenticationSchemes.properties.Authentication will be attempted in the order that they are listed. For example, if theDocbaseLoginAuthentication scheme is listed first, a login dialog is always presentedregardless of a user principal authentication scheme later in the list.



2. Open the file /WEB-INF/classes/com/documentum/web/portal_server/portal_serverEnvironment.properties where portal_server is the short name for your portalserver.

Add the following line and save the file:AuthenticationMode=trusted

3. Encrypt the superuser’s password and paste the encrypted form of the password intoweb.formext.session.TrustedAuthenticatorCredentials.properties. For encryptingthe password, refer to the steps below.

4. Set up J2EE principals in the application deployment description web.xml and inapplication server-specific files. For information on modifying web.xml, refer to theinstructions below. Consult the server documentation for this information.

5. Stop and restart the portal server to enable trusted authentication.In a portal environment, user principal authentication requires that the user log on tothe portal. The portal user name must match the repository user name, although thepasswords do not have to match. After authentication with the portal, a WDK session isestablished automatically and the user can access the Content Server through the WDKportlet components. The user’s privileges in the repository are assigned through theuser’s role or permissions, so that the user does not acquire the superuser’s privileges.The default or preferred repository for the user is stored automatically the first time theuser logs on. This can be changed manually using the Documentum portlet preferences.

The WDK framework uses the Content Server ticketing mechanism to obtain a ticket fora Superuser. The actual user name and the Superuser’s ticket are used to establish aconnection for the user. The user’s identity remains authenticated until a new identityfor the same repository is provided or the repository session terminates via HTTPsession time-out or client logout.

To use the password encryption tool:You can encrypt the Superuser’s password for the repository with the trustedauthenticator tool (com.documentum.web.formext.session.TrustedAuthenticatorTool).

1. From the command line, with com.documentum.web.formext.session.TrustedAuthenticatorTool and the Java SDK in your classpath, run the followingcommand on a single line. Substitute the actual repository password to be encrypted:java -classpath "%CLASSPATH%;T:\app\WEB-INF\classes"TrustedAuthenticatorTool password

The output will look similar to the following:Encrypted: [d7d1d6e383d6d4e1d0], Decrypted: [my.pwd6\]

2. Paste the encrypted form of the password into web.formext.session.TrustedAuthenticatorCredentials.properties. Each repository must have three entries(substitute the actual repository name in the sample entries below):

Repository_name.user



Repository_name.passwordRepository_name.domain

If no domain, then enter the following:Repository_name.domain=

For example:myrepository.user=superuser1myrepository.password=d7d1d6e383d6d4e1d0myrepository.domain=

To set up J2EE principals:To enable J2EE principals to log in to repositories (single login), you must modify thedeployment descriptor file (/WEB-INF/web.xml) and follow the procedures that arespecific to your portal server.

1. In /WEB-INF/web.xml, remove the comments around the security constraintselement. This sets up a user role called “everyone”. The web-resource-name valueshould match the context name of the Web application. For example:<security-constraint><web-resource-collection><web-resource-name></web-resource-name><url-pattern>/*</url-pattern><http-method>POST</http-method><http-method>GET</http-method>

</web-resource-collection><auth-constraint>

<role-name>everyone</role-name></auth-constraint>

</security-constraint>

<login-config><auth-method>BASIC</auth-method>

</login-config>

2. Follow the portal server procedure for setting up J2EE principals. Each portal serverhas its own procedure for enabling single login.

Ticketed LoginA Web application that already has a repository session can link to a WDK-basedapplication using a ticketed login. The ticket logs the user in without a login screen,because the user is already logged in through the calling application.

The link (URL) containing a ticketed login is in the following form (with equals signescaped):http://server_name:port_number/application_name/component/component_name?



locale=locale_code&ticket=DM_TICKET%3d0000001a3dd7626e.repository_name@host_name&username=username&docbase=repository_name

Key:• server_name:port_number

Host-specific alias for accessing the server• application_name

Virtual name for your application, used to access the application• component=component_name

Redirects to a specific component. You can also redirect to an action by substitutingaction=action_name. Specifies a specific component to be launched. If redirecting toan action, specify action name.

• locale=locale_code

Sets the locale for the session using Java locale code. Localized strings for that localemust be present.

• ticket=ticket number

Specifies a ticket that has been generated within the required time frame (default 5minutes) generated by the DFC call getLoginTicket()

• repository_name

Target repository, appended to the ticket with “.”• host_name

WDK application server host name• docbase=repository_name

Name of target repositoryFor example, the following URL contains a login ticket (line breaks inserted for displaypurposes only):http://localhost:8080/portal/component/main?locale=en_US&ticket=DM_TICKET%3d0000001a3dd7626e.viper@denga000&username=randy&docbase=viper

Note: Arguments must escape single quotes as %27 and embedded equalsigns as %3d. The ticket argument in the example above, before escapes, isDM_TICKET=0000001a3dd7626e.viper@denga0008. The argument after escapes isDM_TICKET%3d0000001a3dd7626e.viper@denga0008

The URL can have an optional startupAction parameter so that the action is called afterthe ticketed login. If you specify a startup action, you must also provide required actionarguments in the URL.

In the following example, the startup action arguments are provided to launch the searchcomponent after login (with spaces and embedded equal signs escaped):



http://localhost:8080/webtop/component/main?startupAction=search&query=select%20object_name%20from%20dm_document%20where%20r_object_id%3d%2709aac6c2800015b7%27&queryType=dql&ticket=DM_TICKET%3d0000001a3dd7626e.viper@denga0008&username=testuser&docbase=viper

The ticket is generated by an API call. Your code should generate a new ticket every timea user clicks on the link that launches the WDK-based application.

To get a login ticket for a user who is currently logged in, use DFC calls similar tothe following. (The class that encodes embedded characters to make them URL-safeis java.net.URLEncoder).IDfSession session = null;try{IDfSession sess = loginMgr.getSession();String strPrefix = "http://localhost/wtapp/component/main?ticket=";String ticket = sess.getLoginTicket();String strSuffix = "&username=myname&docbase=myrepository";String fullUrl = strPrefix + URLEncoder.encode(ticket) + strSuffix;System.out.println(fullUrl);

}finally{if(dfsession != null){

releaseSession(session);}

}

Saved credentials authenticationWhen a user logs into a portal, Documentum portlets in the portal present a login dialog.This dialog gives the user the option to save the repository credentials so that the userdoesn’t have to log into the portlets on next access. This authentication is implementedby the SavedCredentialsAuthenticationScheme.

The user can edit saved credentials from any Documentum portlet by clicking thePortal specific link to edit mode. The user must then select yje link to the GeneralDocumentum Preferences.

Single sign-onThe single sign-on (SSO) authentication scheme (not supported) requires strings toauthenticate an HTTP session against a single, specified repository. These values are



specified in the application configuration file app.xml. For application configurationinformation, refer toWeb Development Kit Development Guide.

You must also modify the properties file com.documentum.web.formext.session.AuthenticationSchemes.properties, located in WEB-INF/classes, to make the SSOauthentication scheme first in the list of authentications that are attempted during login.

You must have the dm_netegrity plugin installed in the Content Server, which decodesthe DMSESSION token sent from WDK for authentication. The plugin contacts theNetegrity policy server to verify that the token is valid. Errors in authentication arelogged in the /Documentum/dba/log/dm_netegrity.log file.

Skip authenticationAll components automatically seek authentication if the user does not have asession. If your custom component does not require a repository session, you canconfigure skip authentication for the component. Skip authentication is configuredin the resource file Environment.properties, which is located in the directory/WEB-INF/classes/com/documentum/web/formext. To add a component that skipsauthentication, add a line with the key value non_docbase_component. In the followingexample, the custom component bluesheet does not require a repository session:non_docbase_component.6=bluesheet

You can use JSP pages and server-side classes from your JSP pages that do not requirea repository connection. Do not use these pages within a component so that the logindialog is not called.

Login preferencesThe login component uses the WDK Preferences service to store the following loginsettings in a cookie:

user namerepositorydomainlanguageshow options flag (default true)

When a user changes one of these settings, the new setting is written to the preferencestore. If the user has never chosen a repository or domain, the advanced options areshown regardless of the login component showOptions configuration value.



If the user selects a value (such as a repository) that is valid for one server but not foranother server, the preference is ignored, and the default value for the server is presentedin the login dialog. The user may then select another value through the UI.

Login localeThe initial locale for the UI presentation at login is determined by the locale of the portalserver host. The login component presents a language dropdown control that lists allof the installed locales for the application. When the user selects the locale, the UI isrefreshed with the UI strings of the selected locale.

Number of user sessionsTo set the maximum number of application server sessions, enter an integer value inthe <session_config><max_sessions> element of your custom app.xml file. After themaximum number of sessions has been reached, requests are redirected to the JSP page/wdk/serverBusy.jsp. A value of –1 means that there is no limit to the number of sessions.


Chapter 4Troubleshooting

This chapter provides information on addressing any errors that occur. If an error occurs, portletsprovide information in two ways:• Error messages tell you the nature of the problem and include amore details link that opens an

error page with additional information to help you troubleshoot the error. You can print out theinformation in the error page or mail the information to a system administrator or, if authorized,to our technical support team.

• Tracing tracks and logs what is happening behind the UI of your application.

TracingTracing is one of the most effect ways to track what is happening behind the UI of yourapplication. You can start and stop different levels of tracing, and view the tracing logsto help your team and our team resolve any application issues.

Tracing takes up memory and considerably slows application performance. You shouldnot leave tracing running unless you are trying to narrow down a specific issue. You canstop and start portlet tracing and you can view the tracing logs.

Tracing flags are enumerated in the WDK resource file TraceProp.properties located in/WEB-INF/classes/com/documentum/debug. This file contains all tracing flags thatare defined in your application. If there is an unknown flag in this file, the Trace classinitialization will generate a warning message but will continue.

Note: You must enable tracing for the current session by navigating to/wdk/tracing.jsp and checking the box that enables tracing. You can enabletracing for all sessions by setting SESSIONENABLEDBYDEFAULT to true in/wdk/source/com/documentum/debug/TraceProp.properties.

The following tracing flags can be used to trace portlets:


Troubleshooting

DISPATCHER Traces the Component Dispatcher. Thedispatcher is an internal Documentumtool that does not have any public tracingcapabilities.

ENVIRONMENT Traces current environment, propertiesfile, environment class, environmentcreation, and environment-specific calls.

HTML_PAGE_PROCESSOR Traces tags rewritten for portlets.

HOOK Traces environment lookup, user name,and repository.

PUBLISHED_CONTENT Web Publisher portlet specific flag used totrace searching in the Published Contentportlet. If this flag is turned on it displaysan error for invalid entries in the XMLconfiguration file for example, invalidattribute name and invalid object typename. This flags helps determine whycontainers are not displaying in theportlet, and displays the DQL used tosearch the portlet for each container.

SEARCH Web Publisher portlet specific flag used totrace searching in the Published Contentand Submit Content portlets. If this flag isturned on it displays an error for invalidentries in the XML configuration file inwhich the search component is used forexample, invalid object type name, orinvalid attribute name.

VIRTUALJS Traces HTTP request and responseincluding response status 304 and 200.

WDK_API_TRACE Traces the local path for multi-part HTMLfile upload.


Chapter 5Integrating with Portal Environments

The WDK environment package contains APIs that enable WDK to operate on J2EE applicationservers, JSR-168 compliant portal servers, or non-JSR-168 compliant portal servers. Environmentsare provided for J2EE standalone Web applications and for several JSR-168 compliant portal servers.For certified J2EE application servers, refer toWeb Development Kit Release Notes. For certified portalservers, refer toWDK for Portlets Release Notes.

The following topics describe the configurable and customizable environments in WDK:• Where to integrate WDK into a portal, page 43• Environment classes, page 44• Environment configuration, page 51• Environment APIs, page 51• Registering an environment, page 64• HTML post-processing, page 65

Where to integrate WDK into a portalIf you are using a portal that is listed in the certification table of the WDK for Portletsrelease notes, your portal environment is provided by the installer and you can simplyuse Documentum portlets and components in your application after running the installer.

If you are using a JSR-168 compliant portal that does not have an environment providedby Documentum, you must extend the Jsr168Environment class and provide methodsthat write user preferences using the portal-specific APIs. For an example, refer toWriting user-level preferences, page 57.

If you are using a portal that is not JSR-168 compliant, you must extend thePortalEnvironment class and provide methods that both read and write user preferences.For examples, refer to Writing user-level preferences, page 57 and Reading user-levelpreferences, page 54.


Integrating with Portal Environments

Environment classesThe environment layer is a set of classes in the com.documentum.web.env packagethat comprise base implementations, hooks and interfaces. The Environment classencapsulates an environment’s specific behavior and functionality. WDK instantiatesand uses the registered environment class whenever it requires information from itsenvironment.

A portal-specific environment is implemented as a single Java class thatextends the abstract Environment class and implements one or more of thecom.documentum.web.env interfaces. WDK environments are packaged incom.documentum.web.env.xxx where xxx is the name of the environment; for example,com.documentum.web.env.bea.

WDK instantiates an environment as a singleton object, and all threads call into the singleinstance. All methods implemented for a custom environment must be thread-safe. Ifyou need to store state, the base Environment class provides instance methods to storeand retrieve your attributes in the environment implementation.

The environment layer of WDK consists of a set of classes that provide a number ofstarting places for your integration depending on the type of portal server you have. Theenvironment APIs are shown in the diagram below.



Figure 5-1. Environment class inheritance diagram

The environment classes are the following:• AbstractEnvironment class, page 46

The AbstractEnvironment class is abstract and provides default implementations ofenvironment APIs.

• Environment class, page 47

The Environment class is also abstract. It extends AbstractEnvironment and addsdefault implementations for session and request access, dispatching, encryption,and portal API access.

Note: Many of these APIs must be overridden for specific portals.• AppServerEnvironment class, page 48



The AppServerEnvironment Class provides a configured environment forintegrating with J2EE Application Servers.

• PortalEnvironment class, page 48

The PortalEnvironment class provides a configured environment for non-JSR-168compliant portal servers. If you are integrating with a non-JSR-168 compliant PortalServer then you should extend the PortalEnvironment class.

• Jsr168Environment class, page 48

The Jsr168Environment class provides a configured environment for integratingwith JSR-168 compliant portal servers.

• BeaPortalEnvironment class, page 49

The BeaPortalEnvironment class integrates with the BEA portal server. (For specificversions, refer to the release notes.)

• IbmPortalEnvironment class, page 50

The IbmPortalEnvironment class integrates with the IBM Portal Server. (For specificversions, refer to the release notes.)

• SunPortalEnvironment class, page 50

The SunPortalEnvironment Class integrates with the Sun Portal Server. (For specificversions, refer to the release notes.)

• StandaloneJsr168Environment class, page 51

The StandaloneJsr168Environment class provides a configured environment fortesting portal component functionality outside of a portal.

AbstractEnvironment class

The AbstractEnvironment class provides a set of methods that return the environmentinterface contracts. (For more information on these interfaces, refer to EnvironmentAPIs, page 51.)

The AbstractEnvironment class returns whether the environment is a Portal environmentusing the isPortalEnvironment() method.

The current HttpServletRequest, HttpServletResponse and HttpSession are returnedfrom the getRequest(), getResponse() and getSession() methods.



Environment class

The Environment class is also an abstract class and cannot be instantiated directly.The Environment class provides default implementations for the lifecycle events,security, error handling, page dispatching, action processing, content transfer, branding,environment properties, and attribute storage. These implementations should besufficient for most environments:• Lifecycle

The lifecycle methods store the request, response and session objects in thread safestorage. If you are overriding any of these methods and you need to continueto store the objects in the thread safe storage, then you must call the superclassimplementation.

• Security

The security methods encode and decode passwords and encrypt and decryptthe trusted authenticator password using a Caesar cipher. For details on trustedauthentication, refer to User principal authentication, page 34. Methods also getthe user name, password, and domain.

• Error handling

The error methods get the error URL and handle errors.• Page dispatching

Page dispatching methods include forward and inline dispatch and access to theobject. By default, pages are included and actions are processed before the page isrendered.

• Action processing

The queryExecute() method is provided to test action preconditions• Content transfer mechanism

The content transfer method returns the content transfer mechanism, which isUCF-based by default in portal environments.

• Branding

The Environment class looks for mapping of WDK CSS classes to portal styles. Fordetails on this mapping, refer to Portal styles, page 28

• Environment properties

The getResourceBundle() method returns the properties file that configures theenvironment.

• Attribute storage

Attribute storage methods get, set, and remove attributes from the environment’sthread-safe local store. A log() method is also provided.



AppServerEnvironment class

The AppServerEnvironment class inherits from Environment. TheAppServerEnvironment class is used by WDK for non-portal J2EE applications suchas Webtop. This class includes all of the implementations for running on a J2EEenvironment.

For backwards compatibility with previous versions of WDK, the followingimplementations are in the AppServerEnvironment class:• The encodeUrl() method returns the full path to the JSP page that is to receive the

next post-server event.• The implementations of the IPreference interface hook into the WDK HTTP cookie

store used in previous versions of WDK.

PortalEnvironment class

The PortalEnvironment class inherits from Environment and serves as the superclassfor all portal environment implementations. You can extend this class to support WDKportlets on a non-JSR-168 compliant portal server.

The following methods are implemented:• preprocess()

Turns on pre-processing.• encodeUrl()

Removes the action URL in order to force all server events to be posted via thecomponent dispatcher.

• handleError() and errorAcknowledged()

Report errors to the WDK’s error message service and handles the user event that isgenerated when the user acknowledges an error dialog.

• postProcess()

Turns on post-processing. For more information about post-processing, refer toHTML post-processing, page 65.

Jsr168Environment class

The Jsr168Environment class inherits from PortalEnvironment. You can extendJsr168Environment to integrate WDK portlets into a JSR-168 compliant portal server



that does not have an environment supplied by Documentum. The following methodsare implemented:• Lifecycle events

onRequestStart() and onRequestFinish() provide access to the request events• Session access

The methods getUsername(), getUserPassword(), getDomain(), getDocbaseName(),getUserPrincipal(), and getLocale() provide access to the user’s portal session.

• preProcess()

This method turns on pre-processing.• URL encoding

encodeUrl() returns a JSR-168 action URL.• JavaScript rewriting

namespaceJsMethodName() changes the supplied JavaScript function name to aname unique within the generated web page by prefixing that function with theportlet ID. rewriteScriptTag() prefixes the portlet ID to a supplied JavaScript functionname.

• Link rewriting methods

rewriteATag() rewrites the href and onclick attributes in a JavaScript call to prefix thecall with the portlet ID. This gives the JavaScript call a unique name in the scope ofthe whole web page that is generated.

• Preferences methods

Several methods enumerate preferences and look up or write preference values(user-level or portlet-level, or application-level). The Jsr168Environment classhandles the writing of Portlet level preferences via the writePortletLevelPreference()method. The writing of user level preferences is not covered by the JSR-168specification: They are written by vendor-specific environment classes.

• Error methods

getErrorUrl() method handles errors in a JSR-168 environment, passing the errorto the stack trace.

BeaPortalEnvironment class

The BeaPortalEnvironment class inherits from Jsr168Environment.BeaPortalEnvironment integrates with the BEA portal server. (For specific versions, referto the release notes.) The following methods are implemented:• onRequestStart() gets the BEA personalization object.



• writeUserLevelPreference() writes preferences using the BEA ProfileWrapper andSessionHelper APIs.

• lookupUserLevelPreference() looks up user preferences using the BEAProfileWrapper and SessionHelper APIs.

• getWriteModePreferenceScopes() returns an enumeration of the preference typesthat can be written.

IbmPortalEnvironment class

The IbmPortalEnvironment class inherits from Jsr168Environment.IbmPortalEnvironment integrates with the IBM Portal Server. (For specific versions referto the release notes.) This class implements the following methods:• getUserPrincipal() looks up the user principal for trusted authentication mode.• getWriteModePreferenceScopes() returns an enumeration of the preference types

that can be written.• writeUserLevelPreference() writes preferences using APIs in the

com.ibm.websphere.wmm package.• lookupUserLevelPreference() looks up user preferences in an LDAP server. For

more information on how IBM WebSphere stores user preferences, refer toWDKfor Portlets Installation Guide .

SunPortalEnvironment class

The SunPortalEnvironment class inherits from Jsr168Environment.SunPortalEnvironment integrates with the Sun portal server. (For specific versions referto the release notes.) This class implements the following methods:• getUserPrincipal() looks up the user principal for trusted authentication mode using

classes in the com.iplanet.sso package.• getWriteModePreferenceScopes() returns an enumeration of the preference types

that can be written.• getNamespace() uniquely identifies the HTML for two portlets on the same page

in a Sun portal environment.• writeUserLevelPreference() writes preferences using APIs in the com.iplanet.am.sdk

package.



StandaloneJsr168Environment class

StandaloneJsr168Environment inherits from Jsr168Environment class. TheStandaloneJsr168Environment class replaces the StandaloneEnvironment class whichis deprecated for this release. The StandaloneJsr168Environment is not supported.Documentum uses this class for testing portlets outside of a Portal environment.

Environment congurationAll Documentum environment configuration settings are in the resource filecom.documentum.web.env.environment_package.environment_name.properties. Forexample, the configuration settings for the BEA portal environment are located incom.documentum.web.env.bea.BeaPortalEnvironment.properties.

Environment APIsThe following environment interfaces are available for your environmentimplementation. The implementations provided by Documentum implement variouscombinations of these interfaces:• Authentication

ISuperCredentials, page 52ILogin, page 52ISecurity, page 52

• User informationIPreference (reading and writing preferences), page 53

• Rendering and rewritingIRender, page 59ITag, page 60IJavascriptHandler, page 60ITheme, page 61

• Environment-specific informationILocale, page 61ILifecycle, page 61ISession, page 62IContentTransfer, page 62IMessageService, page 63IError, page 63



IInfo, page 63

ISuperCredentials

The ISuperCredentials interface manages trusted super credentials. Some controlledenvironments do not permit privileged credentials to be stored in a plain text file, evenif they are encoded. With this interface, you can override how the trusted credentialsare obtained.

Implemented by: EnvironmentReturned by: AbstractEnvironment.getSuperCredentialsContract()

ILogin

The ILogin interface allows the environment developer to override the login component.With manual authentication, WDK must establish credentials directly from the user byredirecting new requests to the standard login component for the installed Documentumapplication.

With the ILogin interface you can override the standard login component andreturn a component name for the method getComponentName(). For example, thePortalEnvironment class implements getComponentName() as follows:public String getComponentName(String repository, ArgumentList outArgs){return "portal_login";

}

If the interface is not implemented or returns null, WDK will use the standard logincomponent, as defined by the installed Documentum application.

Implemented by: PortalEnvironmentReturned by: AbstractEnvironment.getLoginContract()

ISecurity

ISecurity defines methods that specify an encoding/decoding algorithm that can thenbe used to encode environment state. Usually used in conjunction with IPreferencewhen preferences are passed over an HTTP connection. The default implementation inthe Environment class makes use of the WDK TrustedAuthenticatorTool to encrypt anddecrypt the supplied strings using a Caesar cipher.



Note: If you write a class that implements IPreference, you will need to handle thesecurity of those preferences. Call the methods listed in the ISecurity interface.

Implemented by: EnvironmentReturned by: AbstractEnvironment.getSecurityContract()

IPreference (reading and writing preferences)

The IPreference interface defines a set of methods for reading and writing individualpreference values. Portal servers provide preference models that are capable of managingpreferences over multiple scopes: user-level, portlet-level, application-level, or more.

At the user level, preferences are accessed by an editing icon or link in a portlet’s titlebar. Documentum’s Preferences component displays the component preferences on acomponent preferences tab and user preferences on a general preferences tab.

At the portlet level, a portal that supports the JSR-168 preference mechanism allowsyou to get portlet preferences, such as the number of folders or files to display in thedrilldown component (specified in the WDK general preferences component definition).If your portal allows you to get these preferences, then your environment class mustimplement only the portal-specific methods to write user preferences, overriding theJsr168Environment class method writeUserLevelPreference(String, String). For details,refer to Writing user-level preferences, page 57.

If your portal does not support the JSR168 preferences mechanism, you will need toimplement preference lookups as well as storage. Your environment class wouldsubclass Jsr168Environment and implement IPreference. For details, refer to Readinguser-level preferences, page 54 and Writing user-level preferences, page 57.

Implemented by: AppServerEnvironment, Jsr168Environment,StandaloneEnvironmentReturned by: AbstractEnvironment.getPreferenceContract()

The following topics describe preference implementation:• Reading user-level preferences, page 54• Writing user-level preferences, page 57• Preference mapping, page 58• Preference scopes, page 58



Reading user-level preferences

If your portal does not support the JSR168 preferences mechanism, you will need toimplement preference lookups using the portal APIs. Your environment class wouldthen subclass Jsr168Environment and implement IPreference.

The following example shows pseudocode to implement IPreference:public class CoolPortalEnvironment extends Jsr168Environmentimplements IPreference

{/*** Lookup configuration preference value as a String* @param strPreference preference name* @param scope the preference scope* @return the preference value*/public String lookupString(String strPreference,EnvironmentConfigScope scope)

throws EnvironmentPreferenceException{// use your portal APIs to lookup a string preference

}

/*** Lookup configuration preference value as a Boolean* @param strPreference preference name* @param scope the preference scope* @return the preference value*/public Boolean lookupBoolean(String strPreference,EnvironmentConfigScope scope)

throws EnvironmentPreferenceException{// use your portal APIs to lookup a boolean preference

}

/*** Lookup configuration preference value as an Integer* @param strPreference preference name* @param scope the preference scope* @return the preference value*/public Integer lookupInteger(String strPreference,EnvironmentConfigScope scope)

throws EnvironmentPreferenceException{// use your portal APIs to lookup an integer preference

}

/*** Write the configuration preference value as a boolean* @param strPreference preference name* @param bValue boolean preference value* @param scope the preference scope* @return success | failure



*/public boolean writeBoolean(String strPreference, Boolean bValue, EnvironmentConfigScope scope)throws EnvironmentPreferenceException{// use your portal APIs to lookup a boolean preference

}

/*** Write the configuration preference value as a string* @param strPreference preference name* @param strValue string preference value* @param scope the preference scope* @return success | failure*/public boolean writeString(String strPreference, String strValue, EnvironmentConfigScope scope)throws EnvironmentPreferenceException

{// use your portal APIs to write a string preference.

}

/*** Write the configuration preference value as an Integer* @param strPreference preference name* @param iValue integer preference value* @param scope the preference scope* @return success | failure*/public boolean writeInteger(String strPreference, Integer iValue, EnvironmentConfigScope scope)throws EnvironmentPreferenceException

{// use your portal APIs to write an integer preference

}

/*** Retrieve an enumeration of preference scopes supported (read mode)* @return enumerations of preferences scopes*/{if(s_arrScopes == null){

s_arrScopes = new ArrayList();s_arrScopes.add(EnvironmentConfigScope.USER);

}return s_arrScopes;}

/*** Retrieve an enumeration of preference scopes supported (write mode)* @return enumerations of preferences scopes*/public ArrayList getWriteModePreferenceScopes(){// use your portal APIs to get writable preferences

}



}

For non-JSR-168 portals, you need to read user preferences using the portal APIs.

This example describes how to read user level preferences.

Example 5-1. Reading user-level preferences

public class ReadUserPrefsEnvironment extends PortalEnvironmentimplements IPreferencepublic String lookupString(String strPreference, EnvironmentConfigScope scope)

throws EnvironmentPreferenceException{

return lookupSetting(strPreference, scope);}

public Boolean lookupBoolean(String strPreference, EnvironmentConfigScope scope){

Boolean bResult = null;String strResult = null;try{strResult = lookupSetting(strPreference, scope);

}catch(EnvironmentPreferenceException e){}if (strResult != null && strResult.length() > 0){

bResult = new Boolean(strResult);}return bResult;

}public Integer lookupInteger(String strPreference, EnvironmentConfigScope scope){

Integer iResult = null;String strResult = null;try{strResult = lookupSetting(strPreference, scope);

}catch(EnvironmentPreferenceException e){}if (strResult != null && strResult.length() > 0){

try{

iResult = new Integer(strResult);}catch(java.lang.NumberFormatException e){

iResult = new Integer(0);}

}return iResult;

}protected String lookupSetting(String strSetting, EnvironmentConfigScope scope)

throws EnvironmentPreferenceException



{String strProperty = null;if(scope == EnvironmentConfigScope.USER){

PortletRequest objRequest = (PortletRequest)this.getAttribute(PORTLET_REQUEST);Map userInfo = (Map) objRequest.getAttribute(PortletRequest.USER_INFO);strProperty = (userInfo!=null) ? (String) userInfo.get(strSetting) : null;

}return strProperty;

}}The getPreferenceScopes() method returns to WDK the Preference scopes theenvironment supports for reading user level preferences. In this example, only Userlevel preferences are supported.

The lookupString(), lookupBoolean() and lookupInteger() methods handle WDK lookingup the string, boolean and integer type preferences respectively.

The lookupSetting() method is a generic helper that helps the lookupString(),lookupBoolean() and lookupInteger() methods with the lookup. ThelookupUserLevelPreference() method retrieves the value for the preference using theJSR-168 API.

Writing user-level preferences

The JSR-168 specification does not cover the writing of user-level preferences. Ifyour portal is not one of the certified portals for which Documentum provides anenvironment, your environment class must write user-level preferences using yourportal APIs. (For non-JSR-168 portals, you must also implement methods that readpreferences. For details, refer to Reading user-level preferences, page 54

The following example overrides the preference for a hypothetical portal environment:public class CoolPortalEnvironment extends Jsr168Environment{/** write a user-level preference* @param strSetting The preference name* @param strValue The preference value* @return boolean Returns true on success* @ throws Throwable*/protected boolean writeUserLevelPreference(String strSetting, String strValue) throws Throwable

{try{//use CoolPortal APIs to write a user-level preference here

}catch(Exception e){



if(Trace.ENVIRONMENT)log("Exception:" + e.getMessage());

}return true;

}}

Preference mapping

If your portal environment does not conform to the WDK environment constraints,you can modify a WDK preference by implementing the IPreference interfaceto map to a preference that meets your environment requirements. The methodexternalizePreference(String strPreference) takes a WDK preference and returnsyour specific environment preference. For example, if your environment does notallow preferences containing numbers, you could implement the mapping of a WDKpreference value of abcd123 in the following way:public String externalizePreference(String strPreference){String strExternalizedPreference = strPreference;if (strPreference.equals(STR_WDK_PREF)){strExternalizedPreference = m_strMyPref;

}

return strExternalizedPreference;}

private String m_strMyPref = abcdaaa;private static final String STR_WDK_PREF = "abcd123";

Preference scopes

The WDK framework will apply an order of precedence scopes when attempting tolookup a preference value. The order of precedence for preferences is defined in theenvironment’s configuration file. The lookup continues until a value is returned or thereare no more scopes to lookup from. If no value is returned by any scope then a defaultvalue will be looked up in the component’s XML configuration file. If that lookup alsoproduces no result, then hard-coded values will be used.

The preference scopes are as follows:• Component preferences

Apply to a single instance of a component, for example, home cabinet folder path. Acomponent preference with the same name overrides the user preference.

• User preferences



Apply to the individual user, for example, the number of items on a page.• Group preferences

Apply to a group, providing default preference values for all users in the group. Auser or component preference with the same name overrides the group preference.(Not implemented)

• Application preferences

Sets default preference values for all users. These preferences are configured in/webcomponent/app.xml.

Additional methods allow the developer to return an enumeration of preference namesand scopes. The following example defines portlet and user preference scopes for theenvironment:/*** Retrieve an enumeration of preference scopes supported (write mode)* @return arraylist of writable preferences scopes*/public ArrayList getWriteModePreferenceScopes(){if(s_arrScopes == null){s_arrScopes = new ArrayList();s_arrScopes.add(EnvironmentConfigScope.PORTLET);s_arrScopes.add(EnvironmentConfigScope.USER);

}return s_arrScopes;

}

IRender

IRender provides a set of methods for rewriting attributes in the WDK component’sHTML response. Portal servers often place requirements on the format of the HTMLthat is returned by a portlet. For example, the portal server may require that action linksmust be valid URLs generated by the portal server API.

The IRender interface provides two sets of methods:• Pre-processing

The preProcess() method tells the framework whether to perform preprocessing. If itreturns true, the environment class encodeURL(), namespaceHtmlElement(), andnamespaceJsMethodName() methods are called to preprocess the form URL, controlnames, and JavaScript functions, respectively when he HTML response is rendered.

• Post-processing

The postProcess() method tells the framework whether to post-process theHTML response by adding rewriters for HTML tags. If your implementation ofpostProcess returns true, you must implement rewriter methods that have the



syntax rewriteXXXTag where XXX is the name of the tag; i.e. rewriteFormTagor rewriteImgTag. For more information about post-processing, refer to HTMLpost-processing, page 65. The PortalEnvironment class post-processes the followingHTML tags:

— DIV

— SPAN

— TABLE

— TD

— TH

— TRFor speed and efficiency it is possible to turn the pre and post processors on or off. Bydefault both processors are off.

Implemented by: AppServerEnvironment, PortalEnvironment, Jsr168Environment,StandaloneEnvironmentReturned by: AbstractEnvironment.getRenderContract()

ITag

The ITag interface allows the environment to specify how standard HTML tags shouldbe rendered. The dmform tag library contains the list of Documentum HTML tags.The default implementation renders standard HTML tags. For example, in a portalenvironment the body tag is rendered as a table tag to comply with JSR-168. However,you can use this interface to provide alternative renditions of HTML tags. Branding isalso implemented via these tags.

Implemented by: PortalEnvironmentReturned by: AbstractEnvironment.getTagContract()

The package com.documentum.web.layout supports this interface.

IJavascriptHandler

The IJavaScriptHandler interface acts as a helper service. The IJavaScriptHandlerinterface parses WDK JavaScript files and changes parts of them in order to scope theglobal variables and functions to the namespace of the generated web page, thus avoidingnaming conflicts with the HTML fragments of other portlet JavaScript functions.

This interface is implemented by ComponentNavigationJSHandler and EventsJSHandler.VirtualJS gets IJavascriptHandler and calls handle().



JavaScript files that must be rewritten should be registered for a handler classthat implements IJavascriptHandler in VirtualJS.properties file, located in/WEB-INF/classes/com/documentum/web/env.

Implemented by: This interface is not implemented by an environment class.Returned by: This interface is not returned.

ITheme

The ITheme interface allows WDK to convert a WDK CSS style into a style used by thehost environment. This should be used to ensure that WDK components adopt the lookand feel of the host environment and the user-selected theme in that environment. Theimplementation of this interface maps a WDK style onto a portal style. By default, thisinterface returns the WDK CSS style name unchanged.

Implemented by: Environment, AppServerEnvironmentReturned by: AbstractEnvironment.getThemeContract()

ILocale

The ILocale interface allows WDK to read the locale and time zone of the externalenvironment. If this interface is not implemented or its methods return null, WDKwill accept defaults from the Java Virtual Machine by calling the static methodsLocale.getDefault() and TimeZone.getDefault(). The JVM inherits these defaults from thehost environment.

Note: The method within this interface does not require a valid HTTP session to beinvoked.

Implemented by: AppServerEnvironment, Jsr168Environment,StandaloneEnvironmentReturned by: AbstractEnvironment.getLocaleContract()

ILifecycle

The ILifecycle interface handles lifecycle events. You can use these methods to initializesession, request state, or call vendor-specific APIs to perform initialization or cleanup. AWeb application has four lifecycle events that occur in the following order:

1. Session start, called once for each user

2. Request start, called once for each WDK component request



3. Request end

4. Session end

With the exception of the ILocale interface, all methods on all other interfaces will becalled within the bounds of a request start and end. For example, every environmentmethod will be called after a request start method and before a request end method.

Implemented by: Environment, AppServerEnvironmentReturned by: This interface is not returned.

ISession

The ISession interface allows you to integrate with the principal-based authenticationservices provided by the J2EE host environment. The contract returns the stringsrequired to manage sessions:• User principal: Returns the principal object representing the currently connected

host environment user.• repository name: Returns the Content Server name associated with the current

session.Implemented by: AppServerEnvironment, Jsr168Environment,StandaloneEnvironmentReturned by: AbstractEnvironment.getSessionContract()

IContentTransfer

Caution: The IContentTransfer interface is deprecated for the 5.3 SP1 release. For the5.3 SP1 release the content transfer mechanism is handled on an installation basis byconfiguring the wdk/app.xml file.

The IContentTransfer interface provides a mechanism for configuring the content transfermechanism used by WDK. Portal applications use HTTP content transfer by default.

Programatically changing the content transfer mechanism affects the whole application.The mechanisms available are:• http: constant=HTTP_CONTENT_TRANSFER• applet: constant=APPLET_CONTENT_TRANSFER• ucf: constant=APPLET_CONTENT_UCF

Implemented by: Environment, AppServerEnvironmentReturned by: AbstractEnvironment.getContentTransferContract()



IMessageService

The IMessageService interface allows you to intercept messages that would otherwise bedestined for WDK’s error message service. For example, the PortalEnvironment classimplements handleError() to get an instance of the portlet session and, from it, the HTTPsession. The error is then saved as a session attribute.

Implemented by: PortalEnvironmentReturned by: AbstractEnvironment.getMessageServiceContract()

IError

The standard J2EE error handling mechanism of a JSP page directive that specifies anerror page is not supported in the JSR-168 portal environment. The IError interfaceoverrides the errorPage JSP page directive and displays errors inline.

When an exception reaches the JSP page, the JSP container forwards to the intendedURL. If that URL is a JSP page, the JSP container makes the exception available to theJSP page via an implicit object called exception. If the standard error page URL is notacceptable for the target environment such as a portal environment, then the developercan override this for all components by implementing getErrorUrl().

Some portal servers do not support forwarding at all, and the mechanism must beoverridden by implementing the onError() method. Like the error page, this method getsthe exception and the JSP Writer. Anything written to the Writer will produce resultsinline, inside the actual Portlet content area itself. If the interface is not implemented orreturns null, the framework will return the standard error component URL as defined bythe installed Documentum application.

Implemented by: Environment, Jsr168EnvironmentReturned by: AbstractEnvironment.getErrorContract()

IInfo

The IInfo interface must be implemented by an environment class. This interfacedefines a set of methods for returning version information about the environmentimplementation itself and the external environment. Used by WDK logging.

Implemented by: EnvironmentReturned by: Environment.getEnvironmentInfo()



Registering an environmentRegistering a new environment is a two stage process using the EnvironmentService.properties file and the wdk/app.xml.

To register an environment:

1. Add the new environment to the EnvironmentService.properties file:# Environment Service Property File

# Environment Class Name - {"PortletContextKeywords_"} + {env class name} = {comma seperated of (case-insensitive) keywords in ServletContext.getServerInfo() }ServletContextKeywords_beaportal=WebLogic ServerServletContextKeywords_ibmportal=IBM WebSphere Application ServerServletContextKeywords_sunportal=Sun Java System Application ServerServletContextKeywords_standaloneportal=WDK Portlet ContainerServletContextKeywords_myportal=My Application Server

The example adds a client environment setting of myportal and a correspondingapplication server information string ofMy Application Server.

2. Add an entry to the wdk/app.xml file within the serverenv element filtered for yourclient environment:</environment>...

<serverenv><filter clientenv=’webbrowser,appintg’>

<class>com.documentum.web.env.app.AppServerEnvironment</class><preferencestoreclass>com.documentum.web.env.HttpPreferences</preferencestoreclass>

</filter><filter clientenv=’beaportal’>

<class>com.documentum.web.env.bea.BeaPortalEnvironment</class><preferencestoreclass>com.documentum.web.env.jsr168.Jsr168Preferences</preferencestoreclass>

</filter><filter clientenv=’ibmportal’>

<class>com.documentum.web.env.ibm.IbmPortalEnvironment</class><preferencestoreclass>com.documentum.web.env.jsr168.Jsr168Preferences</preferencestoreclass>

</filter><filter clientenv=’sunportal’>

<class>com.documentum.web.env.sun.SunPortalEnvironment</class><preferencestoreclass>com.documentum.web.env.jsr168.Jsr168Preferences</preferencestoreclass>

</filter><filter clientenv=’standaloneportal’>

<class>com.documentum.web.env.standalone.StandaloneJsr168Environment</class><preferencestoreclass>com.documentum.web.env.HttpPreferences</preferencestoreclass>

</filter>

<filter clientenv=’myportal’><class>com.documentum.web.env.myportal.MyAppEnvironment</class><preferencestoreclass>com.documentum.web.env.MyAppPreferences</preferencestoreclass>

</filter>

</serverenv></environment>



The example adds values for the location of the class and preferences files for theclient environment setting:• client environment setting = myportal• class file = MyAppEnvironment• preferences file =MyAppPreferences

HTML post-processingPost-processing modifies the HTML that is generated by a component immediatelybefore it is committed back to the client. Post-processing is performed for the supportedportal servers in their respective environment classes.

The HTML produced by WDK components is rendered in a format that is acceptable toits environment. The ITag interface handles how certain HTML tags are rendered at a taglevel. For example, the ITag interface allows you to render HTML <HEAD>, <TITLE> and<BODY> tags, to null in a Portal, where only snippet HTML is required. This is becauseeach Portlet makes up a part of a Portal page.

When a finer level of granularity is required, for example if you wish to modify thesource attribute of the <FORM> tagor the class attribute of the <DIV> tag, you should usepost-processing. Post-processing allows you to modify attributes of any HTML element .

The PortalEnvironment class post-processes the following HTML tags:• DIV• SPAN• TABLE• TD• TH• TRThe IRender interface provides a mechanism for switching on post-processing. Theclass associated with the environments is used to define which HTML tags are to beprocessed. If you implement an environment that post-processes a response, then youwill implement one or more methods of the form rewriteXXXTag() where XXX is thename of the HTML element. All of these methods must take one parameter of typeTag, for example rewriteImgTag(Tag tag). You may use the Tag class, page 66 and theAttribute class, page 66 to inspect or change attributes in the HTML tag immediatelybefore it is returned.

The renderStartTag(), renderTagBody() and renderEndTag() methods render portalspecific versions of the following HTML elements :<dmf:html>, <dmf:head>, <dmf:title>,<dmf:body>.



Tag class

The Tag class is a representation of any valid post-processed HTML tag. The methodswithin the Tag class allow you to set the name of a tag and get and set any associatedattributes for a tag.public final class Tag{

//Public Instance Methodspublic void setName(String strName)public void setAttribute(String strName, Attribute attr)public Attribute getAttribute(String strName)

}

Attribute class

The Attribute class represents a single instance of an attribute of a post-processed tag.The methods within the Attribute class allow you to get the name of an attribute and getand set values for an attribute. In addition, you can get and set the delimiter characterthat will enclose the attribute when it is rendered.public final class Attribute{

//Public Instance Methodspublic Attribute(String strName, String strValue, int chValueDelimChar)public void init(String strName, String strValue, int chValueDelimChar)public String getName()public String getValue()public void setValue(String strValue)public int getValueDelimChar()public void setValueDelimChar(int chValueDelimChar)

}

Post-processing example

If you wish to post-process some HTML tags in a portal environment, you must extendthe PortalEnvironment class or one of its subclasses. Implement the IRender interface inyour environment class. The PortalEnvironment class already implements IRender as itcontains the following behavior:Public Boolean postProcess(){

Return true;}



This example rewrites the class applied to the Table and Tr tags to ensure that any tablesrendered by aWDK component will use the CSS styles as defined by the MyEnvironmentenvironment. The HTML before it is pre-processed is:<table border="1" class="tableStyle"><tr class="tableRowStyle"><th>Heading</th><th>Another Heading</th></tr><tr class="tableRowStyle"><td>row 1, cell 1</td><td>row 1, cell 2</td></tr></table>

The following MyEnvironment class extends the PortalEnvironment class sopost-processing is switched on.public class MyEnvironment extends PortalEnvironment

implements IRender

{public void rewriteTableTag(Tag tag){

Attribute cssclass = tag.getAttribute("class");if (cssclass != null){

cssclass.setValue("myportalTable");}

}public void rewriteTrTag(Tag tag){

Attribute cssclass = tag.getAttribute("class");if (cssclass != null){

cssclass.setValue("myportalTableRow");}

}}

The behavior gets the Class Attribute for the Table and Tr tags and rewrites the value asmyportalTable and myportalTable respectively. The HTML after post-processing is:<table border="1" class="myportalTable"><tr class="myportalTableRow"><th>Heading</th><th>Another Heading</th></tr><tr class="myportalTableRow"><td>row 1, cell 1</td><td>row 1, cell 2</td></tr></table>The tables will now be rendered using the CSS styles defined by the MyPortalenvironment.



Environment hooksA hook is used to retrieve information from the environment. For example, WDK usesthe LocaleHook to get locale and time zone information.

There is one hook for every interface in the env package. The hook class marshals callsmade by WDK and ensures the safety of the calls. If an interface implementation doesnot exist, or returns null, the hook returns a default value. If there is an implementationthen the hook makes the call and returns the result to the calling object. Hook classes willalways end with the word Hook.


Chapter 6Customization Overview

Documentum portlets contain a number of application layers, WDK and Web component layers.

This chapter tells you which Documentum portlets components can be customized. Conceptualinformation for each customizable component is discussed in this chapter and customizationexamples for each component are provided in subsequent chapters.

This chapter covers the following topics:• The custom layer, page 69• What to customize, page 71• Customization process, page 76

The custom layerDocumentum portlets use a customization layer that enable you to keep customizationsin a location separate from the installed product. This allows the custom layer to beeasily migrated after an upgrade or reinstallation.

All customized XML configuration and JSP files should be placed in the custom folderwithin the application. This custom folder is treated as the top-level application layerand overrides the functionality in any lower layers. This also makes it easier to preservecustomizations after product upgrades.

The directory structure of the custom layer is flatter than the application itself. The configsubdirectory holds all XML configuration files, extended from any other applicationlayer, with no subdirectories. The strings subdirectory holds all NLS properties files,placed within /custom/strings/com/documentum/custom.


Customization Overview

Table 6-1. Structure of the custom layer

Directory Contains

custom JSP files extended from any otherapplication layer (no subdirectorystructure)

custom/config XML configuration files extendedfrom any other application layer (nosubdirectory structure)

custom/strings/com/documentum/custom NLS properties files extended from anyother application layer (no subdirectorystructure)

custom/theme Contains any custom themes (branding)that you create. Requires a subdirectorystructure. For more details, refer toWebDevelopment Kit Development Guide.

Custom Java classes are not located in the custom layer. They are located in the WEB-INFdirectory of the application, with the directory structure matching the package. Youshould place your custom classes in /WEB-INF/classes/com/your_ company_name. Thepath to the class file must match the package structure to which your class belongs.Consult a Java reference for information on directory and package structures.

Custom layer denition inheritances and overrides

You can customize a client application by extending client components. You can alsoadd your custom components to the existing client application. You can apply your owncorporate branding to your extended application and override default UI and errormessage strings. When you extend a definition in a XML configuration file in yourapplication, any element that is defined in the custom definition will override that sameelement in the definition that has been extended. If the element is not specified in thecustom definition, that element will be inherited from the component that has beenextended in the XML resource file.

For example, suppose you want to extend the portal_preferences component definition,which includes the section below:<config version=’1.0’>

<scope><component id="portal_preferences" extends="propertysheetcontainer:wdk/config/propertysheetcontainer_component.xml">

<desc>



Preferences component: Container that embeds one or more preferencecomponents within a property sheet.

</desc>

<nlsbundle>com.documentum.webcomponent.environment.preferences.PortalPreferencesNlsProp</nlsbundle>

<helpcontextid>preferences</helpcontextid>

<contains>

<component>general_preferences</component><component>saved_credentials</component>

</contains>

</component></scope>

</config>In this example, if you include the contains element in your extended definition, this willoverwrite all <contains> elements. This means that you must repeat any <component>elements that you want to include in your override. For example, if you wanted to adda single element, in your extended definition you would have to repeat the entire listof components plus add the one additional component.

For example, the portal_preferences component would look like:<config version=’1.0’>

<scope><component id="portal_preferences" extends="portal_preferences:portal/config/library/preferences/portal_preferences_component.xml">

<contains>

<component>general_preferences</component><component>saved_credentials</component><component>extraprefs_preferences</component>

</contains>


</config>The one additional component is extraprefs_preferences.

What to customizeThe WDK customization model supports customization of controls, components,actions, and applications. Controls are customized through JSP tags or through XMLresource files. Components, actions, and applications are customized through XML



configuration files. You can modify the application to reflect your company’s businessprocesses and appearance.

The application customization model enables you to create a custom DocApp andmodify the application templates and files. An application DocApp contains all therepository components you need to properly run the application. Application templatesprovide the layout and other non-content related elements such as JavaScript code youneed to create a Web page.

Note: All customized XML configuration and JSP files should be placed in the customfolder within the application. This custom folder is treated as the top-level applicationlayer and overrides the functionality in any lower layers. This also makes it easier topreserve customizations after product upgrades. For more information on the customlayer and its location, refer to The custom layer, page 69.

Applications

WDK applications have varying numbers of application layers: the WDK layer, thewebcomponent layer and the custom layer. A customized WDK application is a Webclient that configures and extends the components in the WDK and webcomponentlayers.

Layers contain:• components which can be anything from DocApp attributes to application templates

and files• actions which are operations that are typically invoked when a user interacts with

the UI• controls which are Java objects that model the attributes of HTML UI elementsWithin a Web application, application layers are managed by the WDK framework.Application layer directories must be located in the root Web application directory.Application layers can inherit their configuration from a parent application layer. Forexample, the webcomponent layer inherits its application definition from the WDK layer.You configure an application in the application XML configuration file app.xml, which islocated in the root folder of each application layer.

Components

Components are built on top of the WDK infrastructure. The Component class is anextension of the Form class that provides support for configuration lookup, containers,Content Server access, and context-based navigation.



The component dispatcher is a runtime process (Servlet) that is responsible for deliveringthe proper dispatch based on context. It uses the configuration service to find the properphysical implementation.

A component comprises an XML configuration file used to define the combination oflayout (JSP page), behavior, and resource bundles available in the component. Thesedefinitions may be scoped for different contexts. The XML configuration file alsoprescribes the required parameters that must be passed to the component along with theproperties and event handlers that are available in the component.

Each component performs a specific repository task, such as check in or view renditions.A component can be extended and customized through code development by changingthe component definition or the JSP pages associated with it. This allows a component toprovide additional or alternative behavior based on the calling context.

How to determine a component from the user interface

There is no straightforward way to determine which component underlies the portion ofthe UI that you want to modify. One of the difficulties is that many pages are displayedby container components, which provide common layout and behavior for severaldifferent components. For example, the properties container displays the attributes,history, and permissions components.

However, you can identify a component or at least its container in one of the followingways:• Mouse over a link in a particular frame, and the component and JSP for that frame

will be displayed in the status bar.• Click in the frame, then right-click and choose Properties to display the same

information as for the previous method.For example, if you navigate over a link in the portlet, you will see a URL in the statusbar that includes something similar to the following:../Proj/appmanager/app/appDT?_nfpb=true&_windowLabel=DocumentumComponentName_1&_urlType=action&_mode=view&_pageLabel=appPortal_page_2#This identifies the component as the ComponentName component in the app layer,and the JSP mentioned here would be located in the app_home/Proj/ directory in theapplication.

Once you have identified the component, you can look in the reference section of theWDK manual (for the WDK, webcomponent, or Webtop layers) or this manual (for theWeb Publisher portlet layer) to get more information about it. If it is a container, thereference documentation will have more information about which components are usedin that container. You can also get more information about the component’s definition bylooking up the component through listing the application’s components.



Listing the application’s components

Each component is defined in an XML configuration file.

You can view information the entire list of components used in all application layersby viewing the componentlist component at http://host_name:port_number/app_name/component/componentlist. This component presents a display with the followinginformation:• Component ID• Scope (type and application layer)• Whether the component is a container• Location of the XML configuration file, with a link to the file• Description of the component• Path to the JSP file for the component• Path to the file containing the NLS resource strings• Path to the Java class for this component• Parameters that are passed to class methodsThis information is extracted from the XML configuration file for that component, andit presents a handy centralized location from which to view component definitionsfor the application.

Determining which parts of the component to customize

Once you identify the component you want to modify, and which application layerthe component resides in, you should decide which parts of the component must bechanged. If the modification involves extending a current component by modifying aJSP or a properties file, you should refer to the configuration sections of the appropriatedevelopment guide. The generic WDK components from the WDK and webcomponentlayers are included in theWeb Development Kit Development Guide. The Portal specificcomponents are covered in the appropriate Portal Development Guide. If themodification involves extending a component by extending or creating a new Java class,you should follow the sections on customizing Java in the appropriate developmentguide.

If you are changing behavior of a component, you should consider whether the behaviorencapsulates business logic and will be extended to other Documentum clients. If so, youmay want to consider creating a business object rather than building the logic directlyin a WDK component. For more information, refer toWeb Development Kit and ClientApplications Reference Guide and Documentum Foundation Classes (DFC) Development Guide.To ensure successful components and controls, refer to the development guidelineswithin these manuals.



Actions

Actions associate user interface (UI) events such as menu selection with applicationfunctions and are usually launched by a UI element such as a link, button, list item ormenu item, or by a repository operation.

An action consists of an action XML configuration file and an action class thatimplements the action and determines whether a user can perform an action based onpreconditions. The action control on a JSP page, such as a menu item or link, is enabled ifthe preconditions are met. You can configure actions in the action XML configurationfile and by setting the action on a control.

Actions may be scoped to roles, types, or custom contexts.

Controls

Controls render UI features such as buttons, tabs, HTML links. Controls are provided in aJSP tag library, which allows you to configure many aspects of the UI rendered as HTML.Basic controls provide standard Web functionality, and repository-enabled controlsprovide data binding, validation, and formatting. You can configure controls throughthe JSP tag attributes on the JSP page itself and, for certain controls, through XML files.

JSP Pages (forms)

Forms are JSP pages that contain a <dmf:webform> or <dmf:form> tag. A formgenerates HTML form tags and maintains a model of the form state and browser historyon the server. A form can include other forms, but generally there is a one-to-onecorrespondence between a form and a Web page. You can configure forms by changingthe form layout in the JSP page itself.

Events

Events are raised when the user makes changes to elements in a UI form. Events can behandled on the client, by JavaScript event handlers, or on the server. You can configureevents in the JSP pages by specifying the event handlers as control tag attributes andadding your custom client-side event handlers.



Branding

The branding service manages the UI look by themes, which incorporate images andicons, and cascading style sheets (CSS). You can apply styles at any level of granularity:on an individual control, on a component, on a group of components within a container,and on the entire application. You can configure branding through themes, and youregister your brand in the application XML configuration file app.xml. Users select atheme for display in the Preferences component.

Text strings

User interface strings and error messages are externalized into Java *.properties files.These text files allow you to change or localize the text of buttons, links, labels, andmessages without any knowledge of Java. WDK supports localization (translation) of theUI strings through national language support (NLS) lookup. Locales are specified in theapplication XML configuration file app.xml. The localized strings are locale-specific. Theapplication uses the string for the user’s selected locale.

Customization processThis section discusses some guidelines for customizing. Before you begin a customizationproject, you should understand how the directory structure is arranged (for informationon the directory structure, refer to The Documentum web architectural stack, page 16 )and the basic functionality of the application server components.

Customization guidelines

You customize Web Publisher functionality by extending existing client components,or adding your own custom components to the existing application. Extendingcomponents, or adding new components enables you to do the following.• make textual changes to the application, such as changing its branding, locale, strings,

and app.xml settings that override the default user interface and error messages.• make changes to any of the application’s XML or JSP files that do not require Java

class changes• modify existing component definitions without changing the behavior class



Note: You should make these changes to extended component files in the customlayer, not to the original files as installed by the installer. For more information onthe custom layer and its location, refer to The custom layer, page 69.

• make changes that extend or implement the application’s Java code includingcomponent and control classes

• add new components or controls to the application• make changes that add custom Java classes to the application• build new Web applicationsFollowing are suggested guidelines to help you begin your customization:• Set up an IDE

If you develop a Web application using an integrated development environment(IDE), you must configure WDK to run within that IDE. The documentation foryour IDE describes how to set the classpath for your Web application. You mustset the classpath to include WDK libraries in order to run or compile WDK-basedapplications from within your IDE.

The Documentum Java libraries must be referenced in the J2EE server classpathbecause they are outside of the Web application. The home directory must bereferenced in the J2EE server path because it contains native libraries. The installersfor WDK and its client applications set the J2EE server classpath and the path to theDocumentum home directory when you run the installer on the J2EE server host. Formore information, refer toWeb Development Kit and Applications Installation Guide .

If your Java IDE does not include j2ee.jar (or some subset of it) in its librarydirectory, you must install it on your local system and reference it in your IDEclasspath. You must also reference all of the jar files that are installed by theWDK installer to your DOCUMENTUM_HOME directory (default=C:\ProgramFiles\Documentum\shared).

Consult the documentation for your IDE for instructions on how to set up a deployedWeb application for development, debugging, and compilation. The tutorialWebDevelopment Kit and Applications Tutorial describes how to set up NetBeans, a freeJ2EE IDE, to work with WDK.

• Create a custom layer

All customized XML configuration and JSP files should be placed in the customfolder within the application. This custom folder is treated as the top-levelapplication layer and overrides the functionality in any lower layers. This also makesit easier to preserve customizations after product upgrades. For more information onthe custom layer and its location, refer to The custom layer, page 69 .

• Determine the component you want to modify

Once you identify the component you want to modify, and which applicationlayer the component resides in, you should decide which parts of the componentmust be changed. If the modification involves extending a current component by



modifying a JSP or a properties file, you should refer to the configuration sections ofthe appropriate development guide for that application layer. If the modificationinvolves extending a component by extending or creating a new Java class, youshould follow the customizing Java sections of the appropriate development guide.

If you are changing behavior of a component, you should consider whether thebehavior encapsulates business logic and will be extended to other Documentumclients. If so, you may want to consider creating a business object rather thanbuilding the logic directly in a WDK component. For more information, refer toWebDevelopment Kit and Client Applications Reference Guide and Documentum FoundationClasses (DFC) Development Guide. To ensure successful components and controls,refer to the development guidelines within these manuals.

• Find component information

The componentlist component (virtual_root/component/componentlist) displays allof the components in your application. By clicking on a link to a component name,you will see displayed the following information about the component:

— Name of XML configuration file

— NLS bundle name

— Component parameters

— Whether the component is a container

— Whether the component is configurable

— Fully qualified component class name

— Component description from the component definition• Begin modifying components.

You are now ready to start customizing. Customization examples are provided insubsequent chapters, and reference information at the end of this guide.


Part 2

Customization Examples

The following examples demonstrate some of the common steps you can follow to addDocumentum functionality to your portal application:• Chapter 7, Linking To A Documentum Component• Chapter 8, Converting The DQL Editor Component To A Portlet• Chapter 9, Creating A Simple Time Sheet• Chapter 10, Creating A Custom Type Object Grid• Chapter 11, Adding A Logout PortletSample code for these portlets can be downloaded from the Documentum developerweb site http://developer.documentum.com.



Customization Examples


Chapter 7Linking To A Documentum Component

If the portal container supports hyperlinks, you can add a hyperlink in a non-Documentumportlet that launches a WDK component. That component will be displayed in place of the portalframeset. The following example adds a link to a Documentum component and, in the Documentumcomponent, adds a link back to the portal.

Example 7-1. Creating a hyperlink to a componentThe following example adds a hyperlink within a generic portlet to the Documentum Aboutcomponent:<a href="component/about" target="_blank">About this portal</a>

The link is displayed within the portlet, just below the graphic, as shown below:


Linking To A Documentum Component

Figure 7-1. Link to a Documentum component

When the user clicks the link, a Documentum login dialog is displayed in a new window, and then theabout component is displayed in that window. The portal window remains open for other portaloperations.

Example 7-2. Linking back to the portalThe following example adds a link within a Documentum portlet component JSP page that returnsthe user to the portal, as the portal frameset is replaced by the Documentum component:<a href="/portal_name/my.portal">Return to portal</a>

You can add additional links within the Documentum component JSP page to other pages orcomponents, such as the following link to the Documentum drilldown component:<a href="/portal_name/component/drilldown">View Folders</a>

The about component will link back to the portal is shown below. (The about component in thisexample has been changed to suit the portal.) If you are linking to additional components, your firstcomponent JSP should create a frame whose header frame contains a persistent link back to the portal.



Figure 7-2. Linking back to the Portal




Chapter 8Converting The DQL Editor ComponentTo A Portlet

If you wish your WDK-based components to be displayed inline in the portal, with all of thenavigation, style, and preferences benefits that are provided by the portal, you must convert thecomponent to a portlet.

A Documentum portlet consists of the following elements:• Portlet definition in portlet deployment descriptor portlet.xml, specifying

DocumentumComponent as the portlet class and the portlet component name as the value of theelement <portlet-preferences>.<preference>.<value>.

• Portal-specific definition, as required by the portal vendor• Portlet component definition (XML file) that conforms to the WDK component definition

standards. For details, refer toWeb Development Kit and Client Applications Reference Guide .• Portlet JSP fragment with a *.jsp extension, specified as the value of <pages>.<start> in the portlet

component definition• Portlet component class, specified as the value of <class> in the portlet component definition. If no

class is required for the portlet, use com.documentum.web.formext.component.Component.• (Optional) Portlet component NLS resource bundle, specified as the value of <nlsbundle> in the

portlet component definition• (Optional) Portlet component preferences, specified as the value of <preferences> in the portlet

component definition. For more information on creating and configuring portlet preferences,refer to Chapter 5, Integrating with Portal Environments.

Note: Only the first two items in this list are portlet-specific. A <helpcontextid> element is ignoredin the portal environment. For information on how to provide portlet help, refer to Adding portlethelp, page 30.

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


Converting The DQL Editor Component To A Portlet

Example 8-1. Adding a portlet denitionIn the following example, a portlet definition for the dqleditor component is added to the portletapplication deployment descriptor portlet.xml, located in /WEB-INF:<portlet><description>DQLEditor</description><portlet-name>DocumentumDQLEditor</portlet-name><portlet-class>com.documentum.web.env.jsr168.DocumentumComponent</portlet-class><supports><mime-type>text/html</mime-type><portlet-mode>VIEW</portlet-mode><portlet-mode>EDIT</portlet-mode><portlet-mode>HELP</portlet-mode>

</supports><portlet-info><title>Documentum DQL Editor</title>

</portlet-info><portlet-preferences><preference><name>view</name><value>dqleditor</value>

</preference><preference><name>edit</name><value>portlet_preferences</value>

</preference><preference><name>help</name><value>dqleditor</value>

</preference></portlet-preferences>

</portlet>

You may also need to add a portal-specific portlet specification. The following example from BEAWebLogic shows the contents of a dqleditor.portlet file from /portlets/bea81ga:<?xml version="1.0" encoding="UTF-8"?><portal:root xmlns:...><netuix:javaPortlet definitionLabel="DocumentumDQLEditor"title="DQL Editor"/>

</portal:root>

The resulting portlet is displayed inline as shown below:



Figure 8-1. Component converted to portlet




Chapter 9Creating A Simple Time Sheet

You can create a simple form that can be used as a time sheet. The following sections explain how tocreate a portlet for time sheet.

Creating the time sheet portlet denitionAdd a portlet definition in the portlet.xml file located in /WEB-INF/portlet.xml. Theentry in the file looks similar to the following:<portlet>

<description>Timesheet</description><portlet-name>DocumentumTimesheet</portlet-name><portlet-class>com.documentum.web.env.jsr168.DocumentumComponent</portlet-class><supports>

<mime-type>text/html</mime-type><portlet-mode>VIEW</portlet-mode><portlet-mode>EDIT</portlet-mode><portlet-mode>HELP</portlet-mode>

</supports><portlet-info>

<title>Documentum Timesheet</title></portlet-info><portlet-preferences>

<preference><name>view</name><value>timesheet</value>

</preference><preference>

<name>edit</name><value>portlet_preferences</value>

</preference><preference>

<name>help</name><value>timesheet</value>


</portlet>


Creating A Simple Time Sheet

Note: You should not create this portlet definition using the WebLogic Workshop IDE,because it will overwrite the Documentum portlet class DocumentumComponent.Therefore, add the definition to portlet.xml using a text editor.

You must also add portal-specific information as required by your portal. For theWebLogic portal, you need to create the timesheet.portlet file with the following contentin /portlets/bea81ga:<?xml version="1.0" encoding="UTF-8"?><portal:root

xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0portal-support-1_0_0.xsd">

<netuix:javaPortletdefinitionLabel="DocumentumTimesheet"description="My Timesheet" title="Documentum Timesheet"/>

</portal:root>

Creating the time sheet component denitionCreate an XML configuration file timesheet_component.xml in /custom/config thatreferences your custom JSP page and class. Add the following content to the componentdefinition file:<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<config version=’1.0’><scope>

<component id="timesheet"><pages>

<start>/custom/timesheet/timesheet.jsp</start></pages><class>com.mycompany.timesheet.Timesheet</class>


</config>

Creating the time sheet UI (JSP page)Create a JSP page for the time sheet UI in /custom/timesheet.

Note: You need to create the timesheet folder in the custom folder.

Add the following content in the JSP page:<%@ page contentType="text/html; charset=UTF-8" %><%@ page errorPage="/wdk/errorhandler.jsp" %>



<%@ page import="com.documentum.web.form.Form"%><%@ page import="com.mycompany.timesheet.Timesheet" %><%@ page import="com.mycompany.timesheet.TimesheetForm"%><%@ taglib uri="tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head><dmf:webform formclass="com.mycompany.timesheet.TimesheetForm" /><script></script></dmf:head><dmf:body><dmf:form>

<table><tr>

<td><dmf:label name = "Enter" label="Enter the number of hoursfor today"/></td>

<td><dmf:text name="time"/></td></tr><tr>

<td><dmf:button name="Submit" label="Submit"onclick="onSubmitClicked"/>

<dmf:button name="Cancel" label="Cancel"onclick="onCancelClicked"/></td>

</tr><tr><td><dmf:label label="Thanks for submitting."

name="Confirmation"/></td><td> </td>

</tr></table>

</dmf:form></dmf:body></dmf:html>

Creating the time sheet classesCreate the Timesheet and TimesheetForm class files using your J2EE IDE, and instructyour IDE to compile the class files in /PORTAL_APP_HOME/WEB-INF/classes/com/mycompany/timesheet.

Note: These classes do not include implementation to capture the data entered in theform. You can write your own implementation for capturing the data.

The contents of the class files are as follows:

Timesheet class

In this example we are using a separate timesheet class so that the component isaddressable and so can be included in a Portal.



package com.mycompany.timesheet;

import com.documentum.web.formext.component.Component;import com.documentum.web.common.ArgumentList;import java.util.Date;

public class Timesheet extends Component{

public void onInit (ArgumentList arg){

super.onInit(arg);}

}

TimesheetForm class

At runtime this class overrides the component class with the JSP’s webform attributeform class.package com.mycompany.timesheet;

import com.documentum.web.form.Form;import com.documentum.web.form.control.Label;import com.documentum.web.form.control.Text;import com.documentum.web.form.control.Button;import com.documentum.web.common.ArgumentList;

public class TimesheetForm extends Form {

String strValue = "";public void onInit(ArgumentList arg){

getControl("Confirmation", Label.class).setVisible(false);}

public void onSubmitClicked(Button button, ArgumentList arg){

String time = ((Text)getControl("time")).getValue();getControl("Confirmation", Label.class).setVisible(true);((Text)getControl("time")).setValue(strValue);

}

public void onCancelClicked(Button button, ArgumentList arg){

((Text)getControl("time")).setValue(strValue);}

}Restart the portal server so that it picks up your new component class.

The portlet looks like the following after you login to a repository:



Figure 9-1. Simple time sheet portlet




Chapter 10Creating A Custom Type Object Grid

The drilldown portlet allows you to display all objects in a selected cabinet or folder. You maywant to display only a selected object type. For this purpose, use a portlet component that extendsthe objectgrid component.

The following example creates a portlet that displays a custom object type, technical publicationsweb. It displays two custom attributes for the type and allows you to sort on those attributes,Edition and Publish:

Figure 10-1. Custom type object grid

For the working code samples, refer to the Documentum Developer Web site(http://developer.documentum.com).

Example 10-1. Creating the custom grid portlet component denitionCreate a component configuration file, webdocs_component.xml, in /custom/config to defineyour new component. This definition is a copy of the objectgrid component definition, with newcomponent JSP page, new component class, and two new columns:



Creating A Custom Type Object Grid

<?xml version="1.0" encoding="UTF-8" standalone="no"?><config version=’1.0’>

<scope><component id="webdocs"><params></params><pages><start>/custom/webdocs/webdocs.jsp</start>

</pages><class>com.mycompany.webdocs.WebDocs</class><nlsbundle>com.mycompany.webdocs.WebDocsNlsProp</nlsbundle><header visible=’false’/><columns>

<column><attribute>object_name</attribute><label><nlsid>MSG_NAME</nlsid></label><visible>true</visible>

</column><column>

<attribute>title</attribute><label><nlsid>MSG_TITLE</nlsid></label><visible>false</visible>

</column><column>

<attribute>authors</attribute><label><nlsid>MSG_AUTHORS</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_content_size</attribute><label><nlsid>MSG_SIZE</nlsid></label><visible>false</visible>

</column><column>

<attribute>a_content_type</attribute><label><nlsid>MSG_FORMAT</nlsid></label><visible>true</visible>

</column><column>

<attribute>owner_name</attribute><label><nlsid>MSG_OWNER_NAME</nlsid></label><visible>false</visible>

</column><column>

<attribute>group_name</attribute><label><nlsid>MSG_GROUP_NAME</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_creator_name</attribute><label><nlsid>MSG_CREATOR_NAME</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_object_type</attribute><label><nlsid>MSG_OBJECT_TYPE</nlsid></label><visible>false</visible>



</column><column>

<attribute>r_version_label</attribute><label><nlsid>MSG_VERSION_LABEL</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_creation_date</attribute><label><nlsid>MSG_CREATION_DATE</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_modify_date</attribute><label><nlsid>MSG_MODIFIED_DATE</nlsid></label><visible>true</visible>

</column><column>

<attribute>r_modifier</attribute><label><nlsid>MSG_MODIFIER</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_access_date</attribute><label><nlsid>MSG_ACCESS_DATE</nlsid></label><visible>false</visible>

</column><column>

<attribute>r_lock_owner</attribute><label><nlsid>MSG_LOCK_OWNER</nlsid></label><visible>true</visible>

</column><column>

<attribute>tp_edition</attribute><label>Edition</label><visible>true</visible>

</column><column><attribute>tp_web_viewable</attribute><label>Publish?</label><visible>true</visible>

</column></columns>


</config>

Note: When you add columns to the component definition, you must also add them to the JSP page inorder for them to be displayed.

Example 10-2. Creating the Webdocs portlet JSP pageThe JSP page displays a grid of all objects of the custom type with sortable column links as well as aproperties link and an actions link for each document.<%@ page contentType="text/html; charset=UTF-8" %><%@ page errorPage="/wdk/errorhandler.jsp" %><%@ taglib uri="/WEB-INF/tlds/dmform_1_0.tld" prefix="dmf" %>



<%@ taglib uri="/WEB-INF/tlds/dmformext_1_0.tld" prefix="dmfx" %><%@ page import="com.documentum.web.form.Form" %><%@ page import="com.documentum.webcomponent.navigation.objectgrid.ObjectGrid" %><%@ page import="com.documentum.web.form.control.databound.DataProvider" %><%@ page import="com.documentum.web.form.control.databound.Datagrid" %><%@ page import="com.mycompany.webdocs.WebDocs" %>

<dmf:html><dmf:head><dmf:webform /><script language=’JavaScript1.2’ src=’<%=Form.makeUrl(

request, "/wdk/include/popupMenu.js")%>’></script></dmf:head>

<dmf:body cssclass=’contentBackground’ topmargin=’0’ bottommargin=’0’leftmargin=’5’ rightmargin=’5’ marginheight=’0’ marginwidth=’0’>

<dmf:form><%

// Get the objectgrid objectObjectGrid form = (ObjectGrid)pageContext.getAttribute(ObjectGrid.FORM, PageContext.REQUEST_SCOPE);

DataProvider dataProvider = ((Datagrid)form.getControl(ObjectGrid.GRID_NAME, Datagrid.class)).getDataProvider();

//label used on ’view’ linkString strLinkName = form.getAttributeForViewLink();

%>

<dmf:datagrid name=’<%= ObjectGrid.GRID_NAME %>’ paged=’true’...>

<tr valign=’top’><td width=’100%’ height=24><dmf:label cssclass=’drilldownFileInfo’ nlsid=’MSG_SHOW_ITEMS’/><dmf:datapagesize name=’sizer’ preference=’application.display.streamline_files’.../>

</td><td nowrap>

<dmf:datapaging cssclass=’drilldownFileInfo’gotopageclass=’drilldownPager’ name=’<%= ObjectGrid.HEADER_PAGING %>’/>

</tr>

<%if (dataProvider.getResultsCount() > 1){

%>

<tr><td><nobr><b><span class=’drilldownFileInfo’><dmf:label nlsid=’MSG_SORTBY’/>: </span></b><dmf:celllist>

<dmf:celltemplate field=’<%= strLinkName %>’>| <dmf:datasortlink cssclass=’drilldownFileInfo’ name=’sortviewlink’



datafield=’<%= strLinkName %>’ mode=’caseinstext’/></dmf:celltemplate>

<dmf:celltemplate field=’r_lock_owner’>

<dmf:datasortlink cssclass=’drilldownFileInfo’ name=’sort1’datafield=’r_lock_owner’ reversesort=’true’/>

</dmf:celltemplate>

<dmf:celltemplate field=’tp_web_viewable’>| <dmf:datasortlink cssclass=’drilldownFileInfo’ name=’sort5’

datafield=’tp_web_viewable’ reversesort=’true’/></dmf:celltemplate>

<dmf:celltemplate type=’number’>| <dmf:datasortlink cssclass=’drilldownFileInfo’ name=’sort2’

datafield=’CURRENT’ mode=’numeric’/></dmf:celltemplate>

<dmf:celltemplate type=’date’>| <dmf:datasortlink cssclass=’drilldownFileInfo’ name=’sort3’

datafield=’CURRENT’ mode=’numeric’/></dmf:celltemplate>

<dmf:celltemplate>| <dmf:datasortlink cssclass=’drilldownFileInfo’ name=’sort4’

datafield=’CURRENT’/></dmf:celltemplate>

</dmf:celllist></td></tr><%}

%>

<dmf:datagridRow><td valign=top style=’padding-top:6px;padding-left:3px’><dmfx:docbaseicon formatdatafield=’a_content_type’ typedatafield=’r_object_type’ linkcntdatafield=’r_link_cnt’ isvirtualdocdatafield=’r_is_virtual_doc’/><br>

<dmfx:docbaselockicon datafield=’r_lock_owner’ size=’16’/></td>

<td align=left width=’50%’><dmf:celllist><dmf:celltemplate field=’<%= strLinkName %>’><dmf:stringlengthformatter maxlen=’48’><dmf:link name=’view_ctrl’ cssclass=’drilldownFileName’datafield=’<%= strLinkName %>’ onclick=’onClickObject’ >



<dmf:argument name=’objectId’ datafield=’r_object_id’/><dmf:argument name=’type’ datafield=’r_object_type’/>

</dmf:link></dmf:stringlengthformatter></dmf:celltemplate>

<dmfx:actionimage name=’propact’ nlsid=’MSG_PROPERTIES’action=’properties’ src=’icons/info.gif’><dmf:argument name=’objectId’ datafield=’r_object_id’/><dmf:argument name=’type’ datafield=’r_object_type’/>

</dmfx:actionimage>

<dmf:celltemplate field=’tp_edition’><dmf:label cssclass=’drilldownLabel’/>:<dmf:label datafield=’tp_edition’/>

</dmf:celltemplate>

<dmf:celltemplate field=’tp_web_viewable’><dmf:label cssclass=’drilldownLabel’/>:<dmf:booleanformatter><dmf:label datafield="tp_web_viewable" />

</dmf:booleanformatter></dmf:celltemplate>

<dmf:celltemplate field=’r_lock_owner’><dmf:panel datafield=’r_lock_owner’><dmf:label/>:<dmf:label datafield=’r_lock_owner’/></i></dmf:panel>

</dmf:celltemplate>

<dmf:celltemplate field=’path’><dmf:label cssclass=’drilldownLabel’ nlsid=’MSG_PATH’/>:<dmfx:primaryfolderpathlink datafield=’r_object_id’showfullpath=’false’ onclick=’onClickObject’/>

</dmf:celltemplate>

<dmf:celltemplate type=’date’><dmf:label cssclass=’drilldownLabel’/>:<dmf:datevalueformatter type=’short’><dmf:label datafield=’CURRENT’/>

</dmf:datevalueformatter></dmf:celltemplate>

<dmf:celltemplate><dmf:label cssclass=’drilldownLabel’/>:<dmf:label datafield=’CURRENT’/>

</dmf:celltemplate></dmf:celllist></td>

<td width=’50%’><dmfx:actionlinklist name=’<%=ObjectGrid.ACTIONS_LIST%>’>



<dmf:argument name=’objectId’ datafield=’r_object_id’/><dmf:argument name=’type’ datafield=’r_object_type’/><dmf:argument name=’lockOwner’ datafield=’r_lock_owner’/><dmf:argument name=’ownerName’ datafield=’owner_name’/><dmfx:argument name=’folderId’ contextvalue=’folderId’/><dmfx:argument name=’folderPath’ contextvalue=’folderPath’/><dmf:argument name=’contentSize’ datafield=’r_content_size’/><dmf:argument name=’contentType’ datafield=’a_content_type’/><dmf:argument name=’isVirtualDoc’ datafield=’r_is_virtual_doc’/><dmf:argument name=’linkCount’ datafield=’r_link_cnt’/><dmf:argument name=’startworkflowId’ value=’startworkflowdrilldown’/><dmf:argument name=’isReference’ datafield=’i_is_reference’/><dmf:argument name=’tp_edition’ datafield=’tp_edition’/><dmf:argument name=’tp_web_viewable’ datafield=’tp_web_viewable’/>

</dmfx:actionlinklist></td></dmf:datagridRow>

<dmf:nodataRow valign=’top’><td><dmf:label nlsid=’MSG_EMPTY’ />

</td></dmf:nodataRow>

</dmf:datagrid></dmf:form></dmf:body></dmf:html>

Note: Some formatting has been removed to streamline the code example.

Example 10-3. Creating the WebDocs portlet denitionYou must also add a portlet definition in portlet.xml. The entry in /WEB-INF/portlet.xml looks similarto the following:<portlet><description>Documentum Web Docs</description><portlet-name>DocumentumWebDocs</portlet-name><portlet-class>com.documentum.web.env.jsr168.DocumentumComponent</portlet-class><supports><mime-type>text/html</mime-type><portlet-mode>VIEW</portlet-mode><portlet-mode>EDIT</portlet-mode><portlet-mode>HELP</portlet-mode>

</supports><portlet-info><title>Documentum Web Documents</title>

</portlet-info><portlet-preferences><preference><name>view</name><value>webdocs</value>





</portlet>

Note: You cannot create this portlet definition through the WebLogic Workshop IDE, because it willoverwrite the Documentum portlet class DocumentumComponent. Instead, add the definition toportlet.xml with a text editor.

You must also add a portal-specific information as required by your portal server. For the WebLogicportal, you create a Logout.portlet file with the following content:<portal:root xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"

xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="

http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0 portal-support-1_0_0.xsd">

<netuix:javaPortlet definitionLabel="DocumentumWebDocs"title="Documentum Web Documents"/>

</portal:root>

Example 10-4. Creating the WebDocs portlet classYou referenced the webdocs component class in the webdocs component definition. Createthe WebDocs class file in your J2EE IDE and instruct your IDE to compile the class file in/PORTAL_APP_HOME/WEB-INF/classes/com/mycompany/webdocs. This class simply overridesthe query that supplies the data for the object grid. The internal attributes are supplied by the querystring defined in ObjectGrid: r_object_id, object_name ,r_link_cnt, r_is_virtual_doc, owner_name,r_object_type, a_content_type, r_lock_owner ,r_content_size, i_is_reference. The visible attributesare supplied by the list of columns in the component definition.

The class contents are as follows.package com.mycompany.webdocs;import com.documentum.web.common.ArgumentList;import com.documentum.webcomponent.navigation.objectgrid.ObjectGrid;

public class WebDocs extends ObjectGrid{public void onInit(ArgumentList args){super.onInit(args);

}

/*** Supplies the query for the component.* @param strVisibleAttrs visible attributes list* @param args Argument list* @return String the DQL statement for component.*/



protected String getQuery(String strVisibleAttrs, ArgumentList args){StringBuffer strQueryBuf = new StringBuffer(512);strQueryBuf.append("SELECT DISTINCT r_object_id as sortby,").append(strVisibleAttrs).append(INTERNAL_ATTRS).append(" FROM technical_publications_web ORDER BY object_name");

return strQueryBuf.toString();}

}

Compile your class file in the same directory. You will need to set the WDK jar files inDOCUMENTUM_HOME/shared in your IDE classpath so that you are able to compile this file.

Restart the portal server to pick up your new component class and definition.




Chapter 11Adding A Logout Portlet

You can add a logout portlet that logs the user out of all Documentum repositories while maintainingthe portal session. The following example creates a logout portlet.

Example 11-1. Creating the Logout portlet component denitionCreate a component configuration file, logout_component.xml, in /custom/config that defines yournew component. The following example points to the new component:<config version="1.0">

<scope><component id="logout"><pages>

<start>/custom/logout/logout.jsp</start></pages><class>com.mycompany.logout.Logout</class>


</config>

Example 11-2. Creating the Logout portlet JSP pageIn the JSP page, there is a simple logout button and label. The button specifies an onclick eventhandler in the logout component:<%@ page contentType="text/html; charset=UTF-8" %><%@ page errorPage="/wdk/errorhandler.jsp" %><%@ page import="com.documentum.web.form.Form"%><%@ page import="com.mycompany.logout.Logout" %><%@ taglib uri="/WEB-INF/tlds/dmform_1_0.tld" prefix="dmf" %><dmf:html><dmf:head><dmf:webform validation="false"/></dmf:head><dmf:body><dmf:form><table width=’100%’ cellspacing=’0’ cellpadding=’2’ border=’0’ >

<tr><td><dmf:label label="Log out from all repositories"/></td><td align="right"><dmf:button label="Log out"onclick="onLogout" cssclass="buttonLink"/></td>

</tr>


Adding A Logout Portlet

</table></dmf:form></dmf:body></dmf:html>

You must also add a portlet definition in portlet.xml. The entry in /WEB-INF/portlet.xml looks similarto the following:<portlet><description>Documentum Logout</description><portlet-name>DocumentumLogout</portlet-name><portlet-class>com.documentum.web.env.jsr168.DocumentumComponent</portlet-class><supports><mime-type>text/html</mime-type><portlet-mode>VIEW</portlet-mode><portlet-mode>EDIT</portlet-mode><portlet-mode>HELP</portlet-mode>

</supports><portlet-info><title>Documentum Logout</title>

</portlet-info><portlet-preferences><preference><name>view</name><value>logout</value>



</portlet>

Note: You cannot create this portlet definition through the WebLogic Workshop IDE, because it willoverwrite the Documentum portlet class DocumentumComponent. Instead, add the definition toportlet.xml with a text editor.

You must also add a portal-specific information as required by your portal server. For the WebLogicportal, you create a Logout.portlet file with the following content:<portal:root xmlns:netuix="http://www.bea.com/servers/netuix/xsd/controls/netuix/1.0.0"

xmlns:portal="http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="

http://www.bea.com/servers/netuix/xsd/portal/support/1.0.0 portal-support-1_0_0.xsd">

<netuix:javaPortlet definitionLabel="DocumentumLogout"title="Documentum Logout"/>

</portal:root>



Example 11-3. Creating the Logout portlet classYou referenced the logout component class in the logout component definition. Createthe Logout class file in your J2EE IDE and instruct your IDE to compile the class file in/PORTAL_APP_HOME/WEB-INF/classes/com/mycompany/logout. The class contents are as follows.(Error handling code has been removed. For the full example, refer to the Documentum developerWeb site.)package com.mycompany.logout;import com.documentum.fc.client.IDfSessionManager;import com.documentum.web.common.ArgumentList;import com.documentum.web.form.FormProcessor;import com.documentum.web.form.FormTag;import com.documentum.web.form.control.Button;import com.documentum.web.formext.component.Cache;import com.documentum.web.formext.component.Component;import com.documentum.web.formext.session.SessionManagerHttpBinding;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpSession;

public class Logout extends Component{public void onInit (ArgumentList arg){super.onInit(arg);

}

public void onLogout(Button button, ArgumentList arg){try{IDfSessionManager sessionManager =SessionManagerHttpBinding.getSessionManager();sessionManager.clearIdentities();SessionManagerHttpBinding.setCurrentDocbase("");

HttpServletRequest httpRequest = (HttpServletRequest)getPageContext().getRequest().getAttribute("javax.servlet.request");

if(httpRequest == null){httpRequest = (HttpServletRequest)getPageContext().getRequest();

}

if(httpRequest != null){HttpSession session = httpRequest.getSession();session.removeAttribute(FormTag.POSTACTION_LOOKUP);Cache.invalidate(getPageContext().getSession());FormProcessor.refreshFormsInSession(getPageContext().getSession());

setComponentJump("login", getContext());}

}catch(Exception err){



}}

}

Compile your class file in the same directory. You will need to set the WDK jar files inDOCUMENTUM_HOME/shared in your IDE classpath so that you are able to compile this file.

Restart the portal server to pick up your new component class.

The portlet looks like the following, after login to a repository:

Figure 11-1. Logout portlet before logout

When the user clicks the Logout button, the portlet redirects to the login component:

Figure 11-2. Logout portlet after logout


Part 3

Portlet Reference

One of the key differences between older versions of WDK for Portlets and this version isthe merging of the code with the main WDK code. The merging of the code allows thedeveloper to leverage a substantial amount of the WDK features in a Portal environment.The Web Development Kit and Client Applications Development Guide is your primaryreference for these WDK features.

This section of the documentation describes features that are different from WDK forportal environments. The section comprises:• Chapter 12, Portlet Specific Components• Chapter 13, Actions In A Portal Environment


Portlet Reference


Chapter 12Portlet Specic Components

The component in this section is specific to WDK for Portlets and is not available to standaloneWeb applications.

The remainder of the portlet components are used by both portal and standalone Web applications.The component definitions are identical for WDK for Portlets and WDK and so are described inWebDevelopment Kit and Client Applications Development Guide.

Portlet specic componentsThere is only one Portlet specific component — portallogin.

portallogin

Prompts the user with a Please log in link and, when the link is clicked, displays thelogin component. The login dialog is not displayed when the user’s full credentialshave been saved.

Parameters

startUrl URL to forward to. If a startURL is specified, the logincomponent will forward to that URL after successful login. Thisvalue takes precedence over startComponent. The URL must berelative to the root context, not relative to the directory locationof the current JSP page.

startComponent If an entry component name is specified, the login componentwill forward to that component after successful login.


Portlet Specic Components

startPage This parameter sets the component page that will be displayedon forward.

docbase Specifies the repository to log into.

For information on the types of application login, see the section on application loginand authentication in Chapter 3, Portlet Authentication.

Elements

Element Description

showoptions Allows you to hide (false) or display (true) the additionallogin options. The additional login options are hidden(set to false) by default.


Chapter 13Actions In A Portal Environment

There are no specific actions in a Portal environment. Full details of how actions work is contained intheWeb Development Kit and Client Applications Development Guide.

However, there are a number of actions that are not supported, or their behavior is amended, within aPortal environment. These actions are disabled, or their behavior is amended, in one of two ways:• Amending actions using action definition files, page 113• Disabling actions using JSP files, page 114

Amending actions using action denition lesWDK amends the behavior of, or disables, a number of actions for Portal environmentsusing a number of action definition files:• dm_smart_list_actions.xml, page 113• generic_actions.xml, page 114• room_actions.xml, page 114The behavior of actions is amended or disabled by filtering on the client environmentelement, <filter clientenv= ...>. The behavior is disabled by setting the <filterclientenv=’not portal’ ...> and additional behavior is added by setting the <filterclientenv=’portal’ ...>.

dm_smart_list_actions.xmlThe dm_smart_list_actions.xml action definition file contains:<execution class="com.documentum.web.formext.action.LaunchComponentWithPermitCheck">

<permit>read_permit</permit><filter clientenv=’not portal’>

<component>search</component></filter>


Actions In A Portal Environment

<filter clientenv=’portal’><component>search</component><container>searchcontainer</container>

</filter></execution>

This code ensures that the Search Results component, search, is always opened within thesearchcontainer component. This means that the user will always have the functionalityassociated with the searchcontainer component, most importantly the Close button.This allows the user to close the Search Results component and return to the searchor advanced search component.

generic_actions.xmlThe generic_actions.xml action definition file contains two actions that are disabled:<filter clientenv=’not portal’>

<action id=’newprocess’ nlsid=’MSG_NEW_PROCESS’ showifdisabled=’false’/></filter>

This disables the new workflow template action as this is not supported in Portalenvironments.<filter clientenv=’not portal’>

<action id=’newwindow’ nlsid=’MSG_NEW_PROCESS’ showifdisabled=’false’/></filter>

This disables the new window in the same session action as this is not supported inPortal environments.

room_actions.xmlThe room_actions.xml action definition file contains the same actions as thegeneric_actions.xml file.

Disabling actions using JSP lesWDK effectively disables actions for Portal environments by removing the controlsthat initiate them from the UI. Controls are removed from the UI by setting one of thefollowing:• <dmfx:clientenvpanel environment=’not portal’>• <dmfx:clientenvpanel environment=’portal’ reversevisible=’true’>



Controls displayed in the UI are configured in the menubar_body.jsp file. A number ofcontrols for actions are removed from the UI by default:• Buttons in the menu bar for WDK based applications are not required in a Portal

environment:

— Online Help — the client-side event, onclick=’onClickHelp’, is removed.

— About — the about action, action=’about’, is removed.

— Logout — the logout action, action=’logout’, is removed.• There is only limited Virtual Document support in the WDK Portal environments.

Virtual Document actions usually supported in WDK, in the More Actions list, thatare not supported in a Portal environment include:

— setbindingrule

— modifyversionlabels

— savechanges

— addcomponentfromclipboard

— addcomponentfromfileselector

— addnewvirtualdocumentnode

— removevirtualdocumentnode

— reordervirtualdocumentnodes

— newassembly

— freezeassembly

— unfreezeassembly• The new window in the same session action, action=’newwindow’, is disabled

through the JSP.




Index

AAbstractEnvironment class, 46action

definition, 75APIs

environment, 51application

components, 74definition, 72layers, 72model, 21

AppServerEnvironment class, 48architecture

Documentum stack, 16WDK for portlets, 23

attribute class, 66authentication

J2EE, 34manual, 33portlets, 33saved credentials, 38service, 18single sign-on, 38skip, 39

BBeaPortalEnvironment class, 49BOF

service, 18branding

definition, 76

Cclass

inheritance diagram, 45portlet styles, 28portlets, 27

componentconverting to portlet, 85

customize, 74definition, 72model, 20portallogin, 111UI, 73

content server, 18context

introduction, 20control

definition, 75custom layer

definition, 69inheritances and overrides, 70structure, 70

customizecomponent, 74guidelines, 76overview, 69process, 76what to customize, 71

customize exampleconverting component to, 85custom type grid, 95link to component, 81logout portlet, 105

Ddata access

service, 18definition

documentum portlet, 22documentum portlet

what is, 22

Eencryption

password tool, 35environment

configuration, 51


Index

hooks, 68registering, 64

environment class, 44, 47AbstractEnvironment class, 46AppServerEnvironment class, 48BeaPortalEnvironment class, 49environment class, 47IbmPortalEnvironment class, 50Jsr168Environment class, 48PortalEnvironment class, 48StandaloneJsr168Environment

class, 51SunPortalEnvironment class, 50

environment interface, 51IContentTransfer, 62IError, 63IInfo, 63IJavascriptHandler, 60ILifecycle, 61ILocale, 61ILogin, 52IMessageService, 63IPreference, 53IRender, 59ISecurity, 52ISession, 62ISuperCredentials, 52ITag, 60ITheme, 61

environmentsnamespace, 29overview, 43preference mechanism, 53

eventdefinition, 75

Fflags

portlets, 41

Hhelp

portlets, 30hooks

environment, 68HTML post-processing, 65

example, 66

II18N

service, 18IbmPortalEnvironment class, 50IContentTransfer

environment interface, 62IError

environment interface, 63IInfo

environment interface, 63IJavascriptHandler

environment interface, 60ILifecycle

environment interface, 61ILocale

environment interface, 61ILogin

environment interface, 52IMessageService

environment interface, 63inheritance

class diagram, 45installed

portlet files, 22interfaces

environment, 51IPreference

environment interface, 53IRender

environment interface, 59ISecurity

environment interface, 52ISession

environment interface, 62ISuperCredentials

environment interface, 52ITag

environment interface, 60ITheme

environment interface, 61

JJ2EE

application server, 18authentication, 34security, 16

JSPpage (forms) definition, 75standard, 15


Index

JSR 168, 21JSR-168

Jsr168Environment class, 48

Llayer

environment, 44locale

login, 40login

J2EE principal, 34locale, 40manual, 33password encryption, 35portlets, 33preferences, 39saved credentials, 38setting up J2EE principals, 36skip authentication, 39ticketed, 36

Mmax_sessions, 40

Nnamespace

in portlets, 29

Ppassword encryption, 35portal

environments, 43portallogin, 111

Portal JSR 168 server, 18PortalEnvironment class, 48portallogin

component, 111portal, 111

portletclass, 27class styles, 28converting component to, 85custom type grid, 95flags, 41help, 30installed files, 22integrate WDK, 43

link to component, 81login, 33logout, 105namespace, 29refresh, 30styles, 28tracing, 41troubleshooting, 41UI, 28WDK architecture, 23writing, 27

post-processingexample, 66HTML, 65

preferencelogin, 39mapping, 58scope, 58user-level, reading, 54user-level, writing, 57

presentation model, 19principal (J2EE) authentication, 34

Rrefresh

data om a portlet component, 30portlets, 30

registerenvironment, 64

Ssaved credentials authentication, 38scope

preference, 58server

content, 18portal, 18

service layer, 18servlets

standard, 16session pooling

service, 19single sign-on

authentication, 38skip authentication, 39StandaloneJsr168Environment class, 51styles

portlets, 28


Index

SunPortalEnvironment class, 50

Ttag class, 66text strings

definition, 76ticketed

login, 36tracing

portlets, 41troubleshooting

portlets, 41

UUI

portlets, 28user sessions, 40user-level

preference, 54, 57

WWDK

environment layer, 19foundation technologies, 15

XXML configuration, 15