WDK For Portlets 5.3 SP1 Development

Web Development Kit for Portlets
Development Guide
Version: 5.3 SP1

September 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 .................................................................... 15
WDK foundation technologies ..................................................................... 15
The Documentum web architectural stack .................................................... 16
Documentum Content Server .................................................................. 18
J2EE Application or Portal Server............................................................. 18
Service Layer .......................................................................................... 18
The WDK Environment Layer ................................................................. 19
Presentation Model ................................................................................. 19
Component Model.................................................................................. 20
Application Model.................................................................................. 21
What is JSR 168? ......................................................................................... 21
What is a Documentum Portlet? .................................................................. 22
Portlet files ............................................................................................. 22
WDK for Portlets architecture .................................................................. 23
Chapter 2 Creating Documentum Portlets ............................................................. 27

Documentum portlet class........................................................................... 27
Portlet user interface ................................................................................... 28
Portal styles................................................................................................ 28
Namespace in portlets ................................................................................ 29
Portlet refresh............................................................................................. 30
Adding portlet help .................................................................................... 30
Chapter 3 Portlet Authentication ........................................................................... 33

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

Tracing ...................................................................................................... 41
Web Development Kit for Portlets Development Guide 3

Table of Contents
Chapter 5 Integrating with Portal Environments .................................................... 43

Where to integrate WDK into a portal .......................................................... 43
Environment classes ................................................................................... 44
AbstractEnvironment class ...................................................................... 46
Environment class .................................................................................. 47
AppServerEnvironment class .................................................................. 48
PortalEnvironment class ......................................................................... 48
Jsr168Environment class ......................................................................... 48
BeaPortalEnvironment class .................................................................... 49
IbmPortalEnvironment class.................................................................... 50
SunPortalEnvironment class .................................................................... 50
StandaloneJsr168Environment class ......................................................... 51
Environment configuration ......................................................................... 51
Environment APIs ...................................................................................... 51
ISuperCredentials ................................................................................... 52
ILogin .................................................................................................... 52
ISecurity ................................................................................................ 52
IPreference (reading and writing preferences) .......................................... 53
Reading user-level preferences ............................................................ 54
Writing user-level preferences ............................................................. 57
Preference mapping ............................................................................ 58
Preference scopes ............................................................................... 58
IRender .................................................................................................. 59
ITag ....................................................................................................... 60
IJavascriptHandler.................................................................................. 60
ITheme .................................................................................................. 61
ILocale ................................................................................................... 61
ILifecycle ............................................................................................... 61
ISession ................................................................................................. 62
IContentTransfer .................................................................................... 62
IMessageService ..................................................................................... 63
IError..................................................................................................... 63
IInfo ...................................................................................................... 63
Registering an environment ........................................................................ 64
HTML post-processing ............................................................................... 65
Tag class ................................................................................................ 66
Attribute class ........................................................................................ 66
Post-processing example ......................................................................... 66
Environment hooks .................................................................................... 68
Chapter 6 Customization Overview ....................................................................... 69

The custom layer ........................................................................................ 69
Custom layer definition inheritances and overrides................................... 70
What to customize ...................................................................................... 71
Applications........................................................................................... 72
Components........................................................................................... 72
How to determine a component from the user interface ........................ 73
Listing the application’s components.................................................... 74
Determining which parts of the component to customize ...................... 74
Actions .................................................................................................. 75
Controls ................................................................................................. 75
JSP Pages (forms) .................................................................................... 75
Events.................................................................................................... 75
Branding ................................................................................................ 76
Text strings ............................................................................................ 76
4 Web Development Kit for Portlets Development Guide

Table of Contents
Customization process ................................................................................ 76

Customization 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 ............................................................... 89
Creating the time sheet portlet definition ..................................................... 89
Creating the time sheet component definition ............................................... 90
Creating the time sheet UI (JSP page) ........................................................... 90
Creating the time sheet classes..................................................................... 91
Timesheet class....................................................................................... 91
TimesheetForm 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 Specic Components ............................................................... 111
Portlet specific components ....................................................................... 111
portallogin ........................................................................................... 111
Parameters ........................................................................................... 111
Elements .............................................................................................. 112
Chapter 13 Actions In A Portal Environment ......................................................... 113

Amending actions using action definition files............................................ 113
dm_smart_list_actions.xml ........................................................................ 113
generic_actions.xml .................................................................................. 114
room_actions.xml ..................................................................................... 114
Disabling actions using JSP files................................................................. 114

Table of Contents
List of Figures
Figure 1–1. Documentum Web Architectural Stack ............................................................. 17

Figure 1–2. WDK for Portlets Architecture ......................................................................... 24
Figure 5–1. Environment class inheritance diagram ............................................................ 45
Figure 7–1. Link to a Documentum component .................................................................. 82
Figure 7–2. Linking back to the Portal ............................................................................... 83
Figure 8–1. Component converted to portlet ...................................................................... 87
Figure 9–1. Simple time sheet portlet ................................................................................. 93
Figure 10–1. Custom type object grid ................................................................................. 95
Figure 11–1. Logout portlet before logout ......................................................................... 108
Figure 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 portlets
The 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 javadocs
Check the Documentum technical support Web site (support.documentum.com) for revisions of the
documentation. Click the Documentation link to search for documents related to your installed
version of WDK or WDK client application. The support site also provides peer support forums
that are monitored by technical support experts.
The Documentum developer Web site, developer.documentum.com, provides sample code, tips, white
papers, and a wealth of information to assist you in developing Documentum-enabled applications.
Intended audience
This 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 applications
To configure WDK-based applications, you must be familiar with the following
technologies:
• 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

Preface
To customize WDK-based applications, you must be familiar with the above-mentioned

technologies and the following additional languages and standards:
• Java 1.3.1 or 1.4
• Servlet 2.3
• Sun JSR-168 standard for portlets
Terminology
APP_HOME is the root directory of the Documentum Web application or portal
application in your installation. The paths for control, action, and component files are
shown relative to this base location.
This guide uses the following conventions:
Convention Description
Italics Represents a variable name for which you must
provide a value, or a defined term
Represents code samples, commands, user input,
typewriter
and computer output
{curly braces} Indicates a Java or CSS code implementation
<XXX> Represents an XML element or JSP tag as it appears
in an XML or JSP file. End tags are not always
included in examples, unless the element is closed,
for example, <dmf:webform/>.
notdefined=”true” All values for control and action attributes or
component parameters are passed as strings, even
though some are treated as boolean values by the
control, 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 the
value with the corresponding lookup value in the
appropriate localized resource file. The user’s locale
will determine which localized version of the string
is used.

Preface
Documentation resources
The Documentum Web Development Kit contains documentation and source files to
assist you in developing custom Web applications:
• Web Development Kit Development Guide
Contains general configuration, customization, and application-building information
for 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-based
applications.
• 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. (Part
of 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 and
component library, sample code, white papers, and a wealth of information to assist
you in developing Documentum-enabled applications.

Preface
Revision history
The following changes have been made to this document:
Revision History
Revision Date Description

September 2005 Initial document release for 5.3 SP1.

Part 1
The Documentum portlets installer installs WDK runtime, portlets, and components
in a JSR-168 compliant portal server. The WDK runtime for WDK for Portlets differs
somewhat from the runtime for standalone Web applications, but these differences are
not exposed to customizations.
The installation guide for Documentum portlets provides information on installing
WDK for Portlets and runtime into your portal. This part of the documentation notes the
additional WDK framework and portlets for the portal environment.
The configuration and customization guidelines for portal and standalone Web
environments are the same. For application-level configuration information, refer to the
Web Development Kit Development Guide. For control, action, and component configuration
guidelines, refer to the Web Development Kit and Client Applications Reference Guide. For
portlet 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 Overview
You can create components that work in both portal and standalone environments.
Launch the appropriate type of component for a portal or standalone Web application
by using the LaunchComponent action class with a dynamic filter. For information
on dynamic filters, refer to “Dynamic Component Launching” in Web Development Kit
Development Guide.


Chapter 1
Introduction And Overview
The Documentum Web Development Kit (WDK) is a Web application tool set. WDK provides the
following 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
functionality
WDK’s architecture incorporates three models: A presentation model that uses JSP tag libraries
to separate Web page design from behavior, a component model that encapsulates repository
functionality in configurable server-side components, and an application model that consists of a set
of 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 technologies

The 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-supplied
and user-defined. Configuration files make it easy to change the behavior of
components, actions, and applications through simple text editing.
• JSP 1.1

A JSP page is a text file that describes how to process an HTTP request to create
an HTML response. A JSP page in WDK consists of fixed (template) HTML and
dynamic content rendered by JSP tags, expression, and scripting. Most of the UI is
generated by JSP tags that can be configured on the JSP page. JSP pages are compiled
into servlets (Java classes) by the JSP container or by a third-party compiler. These
servlets execute on the server when a JSP page is requested. The servlet performs a
server 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 Java
Runtime Environment (JRE) and, usually, the JSP translator (compiler). Each JSP
page is translated into a servlet class and instantiated every time the JSP page is
requested. Additional WDK servlets provide back-end support for timeout, content
transfer, and virtual link redirection.
• J2EE security
If you set up J2EE security in your J2EE server, you can configure WDK to support
single login. The Java authentication mechanism is used to support sign-on to both
the Web server and the repository. Manual authentication, which has been used for
previous versions of Documentum clients, is also supported.
The Documentum web architectural stack

The Documentum Web stack is illustrated below. The layers in the stack are described
in 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 18
J2EE Application or Portal Server, page 18
Service Layer, page 18
The WDK Environment Layer, page 19
Presentation Model, page 19

Component Model, page 20

Application Model, page 21
Documentum Content Server

The Web architecture stack has at its base the Documentum Content Server. All of
the WDK services and programming model exist to expose the content management
functionality of the Content Server.
J2EE Application or Portal Server

The J2EE server provides an application environment for WDK or other J2EE
applications. 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 in
which WDK portal components can run.
A non-JSR 168 compliant portal server also provides a portal environment that can run
WDK 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 strings
that can be localized or changed for your application. The Java SDK manages
internationalized resources.
• Data access
The DFC session interface and JDBC connectors provide data access.
• Authentication
The framework supports a pluggable authentication scheme and is prepackaged
with several schemes: J2EE Principal authentication, manual authentication, single
sign-on (SSO, unsupported), and ticketed login. Skip authentication allows a
component 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 server
connection pooling. WDK applications take advantage of session pooling, increasing
performance over non-pooled sessions.
The WDK Environment Layer

The environment layer in the WDK framework provides a means of supporting various
types 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 well
as a server-side presentation framework.
The Documentum JSP tags generate HTML widgets and databound tables, lists, and
other presentation scripting to the browser. Server-side control classes provide access to
the control tags and maintain state on the server. A form processor maintains the HTML
form state and lifecycle, which is not possible with standard HTML forms.
In addition to the control tags and server-side control classes, the presentation model
incorporates 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 Documentum
functions or components. A component is composed of one or more JSP pages, supporting
behavior classes, and an XML configuration file. Component JSP pages use WDK
controls and actions from the tag libraries, and each component handles control events
with its own event handlers.
The WDK framework enforces a contract for each component, consisting of parameters
that initialize the component. The component behavior class includes event handlers
that 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. The
component is defined within <component></component> elements in the file. In addition
to contract parameters, the definition includes a component behavior class, an NLS
properties resource bundle, a help context ID, and, sometimes, additional configuration
elements. A component can include other components, acting as a container.
The component dispatcher dispatches a particular component dynamically on the
following criteria:
• Calling context
Context consists of runtime conditions such as object type, current component, or
user role. For example, one component definition is called when the selected object
is a folder, and another component definition is called when the selected object is
a document.
• Component implementation
Several types of component implementation are supported, such as WDK 4.2, raw
JSP pages, WDK 5, or other as specified in the component XML file. For example, if
the component definition specifies that it is a WDK 4.2 component, the component
is dispatched using the 4.2 framework. If the component is a raw JSP page, the
component is dispatched using the J2EE server framework without calling the WDK
5 framework.
Components are often launched by actions. Actions launch components through UI
widgets such as menu items or links. An action can evaluate preconditions to ensure that
the action is valid for the user’s context.

Application Model
A Documentum Web application consists of a set of components and the WDK
application framework, DFC, and native libraries. The WDK application framework
consists 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 following
application environments:
• Application server
An environment for running JSPs, Servlets and EJBs. Documentum’s Webtop
application is built for this environment. Services such as authentication and
configuration are provided by the WDK framework.
• Portal server
An environment for running portlets, JSP pages, and servlets. Services such as
authentication and configuration are provided by the portal server.
A Web application can contain several application layers. The application model
enforces consistent appearance and behavior across all application layers contained
within the root WDK-based application. The J2EE-compliant root context can contain
application layers that inherit application parameters from other application layers. For
example, the base application layer is WDK. The WDK application layer is extended by
the webcomponent application layer. Your custom application layer can then extend the
webcomponent application layer.
Using branding, an application layer can supply themes that provide your application’s
unique appearance through icons, images, and style sheets.
What is JSR 168?

The Sun Java Specification Request (JSR) 168 was created to promote portability of
portlets to different portals. This will be particularly important when a portlet is available
as a Web service, following the Web Services for Remote Portals (WSRP) protocol.
The JSR 168 specification establishes a standard API for creating portlets, which provide
application logic through a portal. The specification defines a set of APIs for portlets and
addresses 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 a
presentation layer to Information Systems.
WDK for Portlets installs Documentum portlets, WDK run time, and WDK
components into a portal Web application in a certified portal server. A single
portlet class, DocumentumComponent, dispatches WDK components for each
portlet. A portlet that dispatches a WDK component must specify its portlet class as
com.documentum.web.env.jsr168.DocumentumComponent.
The components that are dispatched for portlet view and edit modes are specified for
each portlet in portlet.xml. The context-sensitive portlet help file is dispatched to a new
browser 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 not
create a Documentum portlet specifying the portlet class as DocumentumComponent.
The IDE will overwrite the Documentum portlet class and render all Documentum
portlets invalid. If this happens, you can restore the portlet class from your installation
war file.
The following topics describe Documentum portlets:

Portlet files, page 22
WDK 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 custom
portlet 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 Documentum
portlets
• /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. If
Documentum products have already been installed on the host, the pre-existing
home directory is used.
WDK for Portlets architecture

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

Figure 1-2. WDK for Portlets Architecture
The differences between the standalone and portal runtime elements in the environment
layer are summarized below:
• Error handler
IError defines methods for overriding errorPage <%@ page %> directive and for
displaying errors inline.
• Lifecycle event handlers
ILifecycle allows the developer to hook into application lifecycle events to perform
initialization or clean up.
• Locale
ILocale defines a set of methods for reading the Locale and TimeZone of the external
environment.
• Preferences
IPreference defines a set of methods for reading and writing preference values for
components, users, groups, or administrators.
• Rendering

IRender provides a set of methods for rewriting URL attributes in the WDK
component’s HTML response.
• Tag handlers
ITag allows the environment to specify how standard HTML tags should be
rendered.
• Themes
ITheme allows the external environment to convert a WDK CSS style into one
of its own styles.
See Environment APIs, page 51 for more information on these environment interfaces.


Chapter 2
Creating Documentum Portlets
If you are writing portlets to run within a JSR-168 compliant portal application server, you need to
follow the guidelines outlined in the following topics:
• 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 30
For information on adding preferences to a portlet, refer to Chapter 5, Integrating with Portal
Environments.
For information on how to add help for a portlet, refer to Adding portlet help, page 30. For examples
of portlets, refer to Part 2.
Documentum portlet class

Documentum portlets use a single portlet class, com.documentum.web.env.jsr168.
DocumentumComponent which extends javax.portlet.GenericPortlet. This class will
launch the component that you specify for the portlet as the value of the view mode in
portlet.xml and will also provide access to preferences and help for the component using
the preferences and help mode values in portlet.xml.
Caution: If your IDE creates portlets by creating the portlet class, make sure you do
not create a Documentum portlet within the IDE by specifying the portlet class as
DocumentumComponent. The IDE will overwrite the Documentum portlet class and
render all Documentum portlets invalid. If this happens, you can restore the portlet class
from your installation war file.

Portlet user interface

JSP pages in portlets should contain HTML fragments only. The portlet contributes
its content to a larger page, so it cannot be a fully formed HTML page. Use the tags
<dmf:html>, <dmf:head>, and <dmf:body> instead of <HTML>, <HEAD>, <TITLE>,
or <BODY> elements. These tags will be rendered appropriately for both portal and
standalone environments. They enable icon rendition and error handling, so they should
not be omitted from JSP pages that are used in portlets.
Your portlet content will probably be contained within a table cell (<TD>) on the portal
page. You can use default width and height and add width and height preferences to
your portlet XML configuration. The portlet will then use scroll bars if the content is too
large for the available table space. Avoid unnecessary layout elements to reduce the
amount of scrolling needed for your portlet.
Tip: Avoid placing <nobr> tags around table cells to prevent line breaks. This will cause
your portlet to push the portal page wide and may force excessive scrolling when users
view other portlets.
To allow portal users with disabilities to be able to use your portlet, the JSPs should be
fully enabled for keyboard-only control and other assistive technologies. For guidelines
on making your portlet components accessible, refer to Web Development Kit and Client
Applications Reference Guide .
In general, you should minimize the use of iFrames and JavaScript in your portlets,
because support differs between browsers and versions. Do not use popup browser
instances, which will cause the portal to lose track of the current portlet’s state and
history. Some portals provide a widget on the titlebar that allows the user to pop the
portlet up as a new browser window.
Use Java comments rather than HTML comments (<! – comment –>) in your files. HTML
comments are rendered into the output even though they are not visible, increasing the
document size and download time. Java comments similar to the following example are
removed from the rendered source along with Java code:
<% //this is a comment %>
Tip: Give each control in your portlet components a unique name, because they will be
rendered by the portal container into a single HTML page.
Portal styles
Your portlet should use portal style classes that are defined in the portal’s cascading style
sheet. Consult your portal documentation for instructions on setting portlet styles.

In the following example from a portlet JSP page, an input element uses a portal style
class called “portlet-form-input-field”:
<input class="portlet-form-input-field" type="submit">
The .css is loaded by the portal and should not be reloaded by a portlet. For class
definitions and associated values, refer to the JSR-168 specification.
If your component will be used by both portal and standalone applications, then use
the WDK style classes and the environment’s theme mapping interface ITheme. This
interface converts a WDK standard css style into one of the portal styles. By default, this
interface returns the WDK style unchanged. Implement the method mapCssClass() to
perform the mapping. This method has the following signature:
public String mapCssClass (String strCssClass)
Where strCssClass is the WDK CSS class name. Returns the mapped portal style.
You can add a branding image to brand your portlets, replacing the Documentum
logo image in the lower right-hand corner of the portlet rendition. To do this, locate
the path to an image within your portal directories and enter it as the value of the
BrandingImage key in the Environment.properties file for your portal. For example, the
file for the BEA WebLogic portal is named BeaPortalEnvironment.properties, and it is
located 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 image
launches the About component, which can be customized to describe your application.
Namespace in portlets
The JSR-168 specification for portal servers specifies that the URIs, element name
attributes, and JavaScipt methods should be encoded with the namespace of that portlet.
Use the IRender method namespaceElement(strPortletInstanceName) to encode these
elements. In the following example, a form element is encoded for portal PC_202:
<% IRender render = EnvironmentService.getEnvironment().getRenderContract();%>
<FORM method=POST name="<%=render.namespaceElement("form1")%>"
action="">
The form element will then be rendered as follows:
<FORM method=POST name="PC_202_form1" action="">
To encode JavaScript with the portal namespace, WDK provides a servlet, VirtualJS. This
servlet rewrites static JavaScript files to portlet-specific versions, changing method names
and any form variable names that are used to the appropriate portal-specific namespace.
The servlet is used by tag rewrite methods in a portal environment, so that the <include

src=" tags no longer point to static JavaScript files but to dynamic versions hosted by the
servlet. For example, the following JavaScript declaration in a WDK page:
<script src="/wdk/wdk/include/events.js" language="javascript1.2">
</script>
is rewritten to:
<script src="/wdk/virtualjs/PC_202/wdk/include/events.js"
language="javascript1.2">
</script>
The servlet delegates the rewriting of JavaScript files to Java classes that implement the
IJavaScriptHandler interface. JavaScript files that must be rewritten are registered for a
particular handler class by adding entries into the VirtualJS.properties file, located in
/WEB-INF/classes/com/documentum/web/env.
Portlet refresh
You can enable a refresh link in your portlet UI by implementing an onRefreshData()
method in your portlet component class. You must then register your portlet in
PortalEnvironment.properties, 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 component

The following example from the MyObjects class refreshes data when the user clicks
on the Refresh link:
public void onRefreshData()
{
super.onRefreshData();
readConfig();
updateControl();
// force refresh on dataproviders
((Datagrid)getControl(
MYOBJECTS_GRID, Datagrid.class)).getDataProvider().refresh();
}
Adding portlet help

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

When you add a new portlet to portlet.xml, add a value for the help mode preference.
For example, for the portlet DocumentumDrilldown, the help mode is set to the value
cabinets:
<preference>
<name>help</name>
<value>cabinets</value>
</preference>
This help value maps to an HTML file that must be located in /app_root_directory/
language_code/cabinets, for example, /PORTAL_APP_HOME/help/en/Documentum
Portlets/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 is
named DialogContainer.CONTROL_HELPBUTTON. (You must import
com.documentum.web.formext.component.DialogContainer into your JSP page.) Help
buttons with this name will be suppressed in portal environments so that portlet help
can 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 3
Portlet 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 38
The following additional login topics are described in Web Development Kit and Client Applications
Reference Guide:
Skip authentication
Silent login
Explicit login
Login preferences
Login locale
Number 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 the
com.documentum.web.formext.session.AuthenticationSchemes. properties file. Place your preferred
authentication scheme first in this list. Schemes in the list must be numbered sequentially. If none of
the authentication schemes succeed, the dispatcher calls and displays the login component.
In addition to the topics listed above, refer to Web Development Kit and Client Applications Reference
Guide for a description of the authentication configuration elements in app.xml.
Manual authentication
Manual authentication occurs on the first access to a specific repository. The user is
presented with a login dialog upon request of a component that requires a session. Login
to a repository is handled by DocbaseLoginAuthenticationScheme.

In a portal environment, a user must first authenticate against the Portal environment
via the portal’s login page and then authenticate against each Content Server via a
WDK login page.
After a successful Content Server connection, the user’s login information is stored in
the portal server’s preference store using the environment’s IPreference.writeString()
method.
Note: Put DocbaseLoginAuthenticationScheme last in the list of authentication
schemes if you are supporting ticketed or user principal authentication. If the
DocbaseLoginAuthentication scheme is first in the list, the login dialog will always
be presented to the user.
User principal authentication

J2EE principal-based authentication allows a single login to the portal server and
Content Server. Each portal server has its own documented procedures for setting up
server-based authentication.
WDK supports server-authenticated users by means of a trusted authenticator credentials
for each repository. The identity of the user who logs in to the Web application must
match the login identity in the repository. This identity (username) is then passed to
the Web application, but the user’s password is not passed. WDK then logs into the
repository for the user by employing a trusted authenticator identity. The trusted
authenticator 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 to
the connection broker that is used by the portlet container host
• SingleDocbasePerDocbrokerAuthenticationScheme
Supports login to a single repository when only one repository projects to the
connection 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 schemes

above is listed first in the list of authentication schemes in the file
com.documentum.web.formext.session.AuthenticationSchemes.properties.
Authentication will be attempted in the order that they are listed. For example, if the
DocbaseLoginAuthentication scheme is listed first, a login dialog is always presented
regardless 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 portal
server.
Add the following line and save the file:
AuthenticationMode=trusted
3. Encrypt the superuser’s password and paste the encrypted form of the password into
web.formext.session.TrustedAuthenticatorCredentials.properties. For encrypting
the password, refer to the steps below.
4. Set up J2EE principals in the application deployment description web.xml and in
application server-specific files. For information on modifying web.xml, refer to the
instructions 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 to
the portal. The portal user name must match the repository user name, although the
passwords do not have to match. After authentication with the portal, a WDK session is
established automatically and the user can access the Content Server through the WDK
portlet components. The user’s privileges in the repository are assigned through the
user’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 the
user 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 for
a Superuser. The actual user name and the Superuser’s ticket are used to establish a
connection for the user. The user’s identity remains authenticated until a new identity
for the same repository is provided or the repository session terminates via HTTP
session time-out or client logout.
To use the password encryption tool:

You can encrypt the Superuser’s password for the repository with the trusted
authenticator 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 following
command 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.password
Repository_name.domain
If no domain, then enter the following:
Repository_name.domain=
For example:
myrepository.user=superuser1
myrepository.password=d7d1d6e383d6d4e1d0
myrepository.domain=
To set up J2EE principals:

To enable J2EE principals to log in to repositories (single login), you must modify the
deployment descriptor file (/WEB-INF/web.xml) and follow the procedures that are
specific to your portal server.
1. In /WEB-INF/web.xml, remove the comments around the security constraints
element. This sets up a user role called “everyone”. The web-resource-name value
should 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 server
has its own procedure for enabling single login.
Ticketed Login
A Web application that already has a repository session can link to a WDK-based
application 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 sign
escaped):
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 substituting
action=action_name. Specifies a specific component to be launched. If redirecting to
an action, specify action name.
• locale=locale_code
Sets the locale for the session using Java locale code. Localized strings for that locale
must be present.
• ticket=ticket number
Specifies a ticket that has been generated within the required time frame (default 5
minutes) 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 repository
For example, the following URL contains a login ticket (line breaks inserted for display
purposes 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 equal
signs as %3d. The ticket argument in the example above, before escapes, is
DM_TICKET=0000001a3dd7626e.viper@denga0008. The argument after escapes is
DM_TICKET%3d0000001a3dd7626e.viper@denga0008
The URL can have an optional startupAction parameter so that the action is called after
the ticketed login. If you specify a startup action, you must also provide required action
arguments in the URL.
In the following example, the startup action arguments are provided to launch the search
component 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 time
a 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 to
the following. (The class that encodes embedded characters to make them URL-safe
is 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 authentication

When 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 user
doesn’t have to log into the portlets on next access. This authentication is implemented
by the SavedCredentialsAuthenticationScheme.
The user can edit saved credentials from any Documentum portlet by clicking the
Portal specific link to edit mode. The user must then select yje link to the General
Documentum Preferences.
Single sign-on
The single sign-on (SSO) authentication scheme (not supported) requires strings to
authenticate an HTTP session against a single, specified repository. These values are

specified in the application configuration file app.xml. For application configuration

information, refer to Web 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 SSO
authentication 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 decodes
the DMSESSION token sent from WDK for authentication. The plugin contacts the
Netegrity policy server to verify that the token is valid. Errors in authentication are
logged in the /Documentum/dba/log/dm_netegrity.log file.
Skip authentication
All components automatically seek authentication if the user does not have a
session. If your custom component does not require a repository session, you can
configure skip authentication for the component. Skip authentication is configured
in the resource file Environment.properties, which is located in the directory
/WEB-INF/classes/com/documentum/web/formext. To add a component that skips
authentication, add a line with the key value non_docbase_component. In the following
example, 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 require
a repository connection. Do not use these pages within a component so that the login
dialog is not called.
Login preferences
The login component uses the WDK Preferences service to store the following login
settings in a cookie:
user name
repository
domain
language
show options flag (default true)
When a user changes one of these settings, the new setting is written to the preference
store. If the user has never chosen a repository or domain, the advanced options are
shown 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 for
another server, the preference is ignored, and the default value for the server is presented
in the login dialog. The user may then select another value through the UI.
Login locale
The initial locale for the UI presentation at login is determined by the locale of the portal
server host. The login component presents a language dropdown control that lists all
of the installed locales for the application. When the user selects the locale, the UI is
refreshed with the UI strings of the selected locale.
Number of user sessions

To set the maximum number of application server sessions, enter an integer value in
the <session_config><max_sessions> element of your custom app.xml file. After the
maximum 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 4
Troubleshooting
This chapter provides information on addressing any errors that occur. If an error occurs, portlets
provide information in two ways:
• Error messages tell you the nature of the problem and include a more details link that opens an
error page with additional information to help you troubleshoot the error. You can print out the
information 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.
Tracing
Tracing is one of the most effect ways to track what is happening behind the UI of your
application. You can start and stop different levels of tracing, and view the tracing logs
to help your team and our team resolve any application issues.
Tracing takes up memory and considerably slows application performance. You should
not leave tracing running unless you are trying to narrow down a specific issue. You can
stop 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 that
are defined in your application. If there is an unknown flag in this file, the Trace class
initialization 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 enable
tracing 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. The

dispatcher is an internal Documentum
tool that does not have any public tracing
capabilities.
ENVIRONMENT Traces current environment, properties
file, environment class, environment
creation, 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 to
trace searching in the Published Content
portlet. If this flag is turned on it displays
an error for invalid entries in the XML
configuration file for example, invalid
attribute name and invalid object type
name. This flags helps determine why
containers are not displaying in the
portlet, and displays the DQL used to
search the portlet for each container.
SEARCH Web Publisher portlet specific flag used to
trace searching in the Published Content
and Submit Content portlets. If this flag is
turned on it displays an error for invalid
entries in the XML configuration file in
which the search component is used for
example, invalid object type name, or
invalid attribute name.
VIRTUALJS Traces HTTP request and response
including response status 304 and 200.
WDK_API_TRACE Traces the local path for multi-part HTML
file upload.

Chapter 5
Integrating with Portal Environments
The WDK environment package contains APIs that enable WDK to operate on J2EE application
servers, JSR-168 compliant portal servers, or non-JSR-168 compliant portal servers. Environments
are provided for J2EE standalone Web applications and for several JSR-168 compliant portal servers.
For certified J2EE application servers, refer to Web Development Kit Release Notes. For certified portal
servers, refer to WDK 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 portal

If you are using a portal that is listed in the certification table of the WDK for Portlets
release notes, your portal environment is provided by the installer and you can simply
use 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 provided
by Documentum, you must extend the Jsr168Environment class and provide methods
that write user preferences using the portal-specific APIs. For an example, refer to
Writing user-level preferences, page 57.
If you are using a portal that is not JSR-168 compliant, you must extend the
PortalEnvironment class and provide methods that both read and write user preferences.
For examples, refer to Writing user-level preferences, page 57 and Reading user-level
preferences, page 54.

Environment classes
The environment layer is a set of classes in the com.documentum.web.env package
that comprise base implementations, hooks and interfaces. The Environment class
encapsulates an environment’s specific behavior and functionality. WDK instantiates
and uses the registered environment class whenever it requires information from its
environment.
A portal-specific environment is implemented as a single Java class that
extends the abstract Environment class and implements one or more of the
com.documentum.web.env interfaces. WDK environments are packaged in
com.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 single
instance. All methods implemented for a custom environment must be thread-safe. If
you need to store state, the base Environment class provides instance methods to store
and retrieve your attributes in the environment implementation.
The environment layer of WDK consists of a set of classes that provide a number of
starting places for your integration depending on the type of portal server you have. The
environment 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 of
environment APIs.
• Environment class, page 47
The Environment class is also abstract. It extends AbstractEnvironment and adds
default 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 for

integrating with J2EE Application Servers.
• PortalEnvironment class, page 48
The PortalEnvironment class provides a configured environment for non-JSR-168
compliant portal servers. If you are integrating with a non-JSR-168 compliant Portal
Server then you should extend the PortalEnvironment class.
• Jsr168Environment class, page 48
The Jsr168Environment class provides a configured environment for integrating
with JSR-168 compliant portal servers.
• BeaPortalEnvironment class, page 49
The BeaPortalEnvironment class integrates with the BEA portal server. (For specific
versions, refer to the release notes.)
• IbmPortalEnvironment class, page 50
The IbmPortalEnvironment class integrates with the IBM Portal Server. (For specific
• SunPortalEnvironment class, page 50
The SunPortalEnvironment Class integrates with the Sun Portal Server. (For specific
• StandaloneJsr168Environment class, page 51
The StandaloneJsr168Environment class provides a configured environment for
testing portal component functionality outside of a portal.
AbstractEnvironment class
The AbstractEnvironment class provides a set of methods that return the environment
interface contracts. (For more information on these interfaces, refer to Environment
APIs, page 51.)
The AbstractEnvironment class returns whether the environment is a Portal environment
using the isPortalEnvironment() method.
The current HttpServletRequest, HttpServletResponse and HttpSession are returned
from 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 be
sufficient for most environments:
• Lifecycle
The lifecycle methods store the request, response and session objects in thread safe
storage. If you are overriding any of these methods and you need to continue
to store the objects in the thread safe storage, then you must call the superclass
implementation.
• Security
The security methods encode and decode passwords and encrypt and decrypt
the trusted authenticator password using a Caesar cipher. For details on trusted
authentication, refer to User principal authentication, page 34. Methods also get
the 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 the
object. By default, pages are included and actions are processed before the page is
rendered.
• Action processing
The queryExecute() method is provided to test action preconditions
• Content transfer mechanism
The content transfer method returns the content transfer mechanism, which is
UCF-based by default in portal environments.
• Branding
The Environment class looks for mapping of WDK CSS classes to portal styles. For
details on this mapping, refer to Portal styles, page 28
• Environment properties
The getResourceBundle() method returns the properties file that configures the
environment.
• Attribute storage
Attribute storage methods get, set, and remove attributes from the environment’s
thread-safe local store. A log() method is also provided.

AppServerEnvironment class
The AppServerEnvironment class inherits from Environment. The
AppServerEnvironment class is used by WDK for non-portal J2EE applications such
as Webtop. This class includes all of the implementations for running on a J2EE
environment.
For backwards compatibility with previous versions of WDK, the following
implementations 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 superclass
for all portal environment implementations. You can extend this class to support WDK
portlets 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 the
component dispatcher.
• handleError() and errorAcknowledged()
Report errors to the WDK’s error message service and handles the user event that is
generated when the user acknowledges an error dialog.
• postProcess()
Turns on post-processing. For more information about post-processing, refer to
HTML post-processing, page 65.
Jsr168Environment class
The Jsr168Environment class inherits from PortalEnvironment. You can extend
Jsr168Environment to integrate WDK portlets into a JSR-168 compliant portal server

that does not have an environment supplied by Documentum. The following methods
are 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 a
name unique within the generated web page by prefixing that function with the
portlet ID. rewriteScriptTag() prefixes the portlet ID to a supplied JavaScript function
name.
• Link rewriting methods
rewriteATag() rewrites the href and onclick attributes in a JavaScript call to prefix the
call with the portlet ID. This gives the JavaScript call a unique name in the scope of
the 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 class
handles the writing of Portlet level preferences via the writePortletLevelPreference()
method. The writing of user level preferences is not covered by the JSR-168
specification: They are written by vendor-specific environment classes.
• Error methods
getErrorUrl() method handles errors in a JSR-168 environment, passing the error
to the stack trace.
BeaPortalEnvironment class
The BeaPortalEnvironment class inherits from Jsr168Environment.
BeaPortalEnvironment integrates with the BEA portal server. (For specific versions, refer
to the release notes.) The following methods are implemented:
• onRequestStart() gets the BEA personalization object.

• writeUserLevelPreference() writes preferences using the BEA ProfileWrapper and

SessionHelper APIs.
• lookupUserLevelPreference() looks up user preferences using the BEA
ProfileWrapper and SessionHelper APIs.
• getWriteModePreferenceScopes() returns an enumeration of the preference types
that can be written.
IbmPortalEnvironment class
The IbmPortalEnvironment class inherits from Jsr168Environment.
IbmPortalEnvironment integrates with the IBM Portal Server. (For specific versions refer
to the release notes.) This class implements the following methods:
• getUserPrincipal() looks up the user principal for trusted authentication mode.
• 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 to WDK
for Portlets Installation Guide .
SunPortalEnvironment class
The SunPortalEnvironment class inherits from Jsr168Environment.
SunPortalEnvironment integrates with the Sun portal server. (For specific versions refer
to 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.
• 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. The
StandaloneJsr168Environment class replaces the StandaloneEnvironment class which
is deprecated for this release. The StandaloneJsr168Environment is not supported.
Documentum uses this class for testing portlets outside of a Portal environment.
Environment conguration
All Documentum environment configuration settings are in the resource file
com.documentum.web.env.environment_package.environment_name.properties. For
example, the configuration settings for the BEA portal environment are located in
com.documentum.web.env.bea.BeaPortalEnvironment.properties.
Environment APIs
The following environment interfaces are available for your environment
implementation. The implementations provided by Documentum implement various
combinations of these interfaces:
• Authentication
ISuperCredentials, page 52
ILogin, page 52
ISecurity, page 52
• User information
IPreference (reading and writing preferences), page 53
• Rendering and rewriting
IRender, page 59
ITag, page 60
IJavascriptHandler, page 60
ITheme, page 61
• Environment-specific information
ILocale, page 61
ILifecycle, page 61
ISession, page 62
IContentTransfer, page 62
IMessageService, page 63
IError, page 63

IInfo, page 63
ISuperCredentials
The ISuperCredentials interface manages trusted super credentials. Some controlled
environments do not permit privileged credentials to be stored in a plain text file, even
if they are encoded. With this interface, you can override how the trusted credentials
are obtained.
Implemented by: Environment
Returned 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 by
redirecting new requests to the standard login component for the installed Documentum
application.
With the ILogin interface you can override the standard login component and
return a component name for the method getComponentName(). For example, the
PortalEnvironment 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 login
component, as defined by the installed Documentum application.
Implemented by: PortalEnvironment
Returned by: AbstractEnvironment.getLoginContract()
ISecurity
ISecurity defines methods that specify an encoding/decoding algorithm that can then
be used to encode environment state. Usually used in conjunction with IPreference
when preferences are passed over an HTTP connection. The default implementation in
the Environment class makes use of the WDK TrustedAuthenticatorTool to encrypt and
decrypt the supplied strings using a Caesar cipher.

Note: If you write a class that implements IPreference, you will need to handle the
security of those preferences. Call the methods listed in the ISecurity interface.
Returned by: AbstractEnvironment.getSecurityContract()
IPreference (reading and writing preferences)

The IPreference interface defines a set of methods for reading and writing individual
preference values. Portal servers provide preference models that are capable of managing
preferences 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 title
bar. Documentum’s Preferences component displays the component preferences on a
component preferences tab and user preferences on a general preferences tab.
At the portlet level, a portal that supports the JSR-168 preference mechanism allows
you to get portlet preferences, such as the number of folders or files to display in the
drilldown component (specified in the WDK general preferences component definition).
If your portal allows you to get these preferences, then your environment class must
implement only the portal-specific methods to write user preferences, overriding the
Jsr168Environment 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 to
implement preference lookups as well as storage. Your environment class would
subclass Jsr168Environment and implement IPreference. For details, refer to Reading
user-level preferences, page 54 and Writing user-level preferences, page 57.
Implemented by: AppServerEnvironment, Jsr168Environment,
StandaloneEnvironment
Returned 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 to
implement preference lookups using the portal APIs. Your environment class would
then subclass Jsr168Environment and implement IPreference.
The following example shows pseudocode to implement IPreference:
public class CoolPortalEnvironment extends Jsr168Environment
implements 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
*/
public Boolean lookupBoolean(String strPreference,
{
// use your portal APIs to lookup a boolean preference
}
/**
* Lookup configuration preference value as an Integer
*/
public Integer lookupInteger(String strPreference,
{
// use your portal APIs to lookup an integer preference
}
/**
* Write the configuration preference value as a boolean
* @param bValue boolean preference value
* @return success | failure

*/
public boolean writeBoolean(
String strPreference, Boolean bValue, EnvironmentConfigScope scope)
{
// use your portal APIs to lookup a boolean preference
}
/**
* Write the configuration preference value as a string
* @param strValue string preference value
*/
public boolean writeString(
String strPreference, String strValue, EnvironmentConfigScope scope)
{
// use your portal APIs to write a string preference.
}
/**
* Write the configuration preference value as an Integer
* @param iValue integer preference value
*/
public boolean writeInteger(
String strPreference, Integer iValue, EnvironmentConfigScope scope)
{
// 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 PortalEnvironment
implements IPreference
public String lookupString(String strPreference, EnvironmentConfigScope scope)
{
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)

{
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 the
environment supports for reading user level preferences. In this example, only User
level preferences are supported.
The lookupString(), lookupBoolean() and lookupInteger() methods handle WDK looking
up 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. The
lookupUserLevelPreference() method retrieves the value for the preference using the
JSR-168 API.
Writing user-level preferences
The JSR-168 specification does not cover the writing of user-level preferences. If
your portal is not one of the certified portals for which Documentum provides an
environment, your environment class must write user-level preferences using your
portal APIs. (For non-JSR-168 portals, you must also implement methods that read
preferences. 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 interface
to map to a preference that meets your environment requirements. The method
externalizePreference(String strPreference) takes a WDK preference and returns
your specific environment preference. For example, if your environment does not
allow preferences containing numbers, you could implement the mapping of a WDK
preference 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 to
lookup a preference value. The order of precedence for preferences is defined in the
environment’s configuration file. The lookup continues until a value is returned or there
are no more scopes to lookup from. If no value is returned by any scope then a default
value will be looked up in the component’s XML configuration file. If that lookup also
produces 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. A
component 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. A
user 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 names
and scopes. The following example defines portlet and user preference scopes for the
environment:
/**
* 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’s
HTML response. Portal servers often place requirements on the format of the HTML
that is returned by a portlet. For example, the portal server may require that action links
must 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 it
returns true, the environment class encodeURL(), namespaceHtmlElement(), and
namespaceJsMethodName() methods are called to preprocess the form URL, control
names, and JavaScript functions, respectively when he HTML response is rendered.
• Post-processing
The postProcess() method tells the framework whether to post-process the
HTML response by adding rewriters for HTML tags. If your implementation of
postProcess returns true, you must implement rewriter methods that have the

syntax rewriteXXXTag where XXX is the name of the tag; i.e. rewriteFormTag
or rewriteImgTag. For more information about post-processing, refer to HTML
post-processing, page 65. The PortalEnvironment class post-processes the following
HTML tags:
— DIV
— SPAN
— TABLE
— TD
— TH
— TR
For speed and efficiency it is possible to turn the pre and post processors on or off. By
default both processors are off.
Implemented by: AppServerEnvironment, PortalEnvironment, Jsr168Environment,
Returned by: AbstractEnvironment.getRenderContract()
ITag
The ITag interface allows the environment to specify how standard HTML tags should
be rendered. The dmform tag library contains the list of Documentum HTML tags.
The default implementation renders standard HTML tags. For example, in a portal
environment 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 is
also implemented via these tags.
Returned by: AbstractEnvironment.getTagContract()
The package com.documentum.web.layout supports this interface.
IJavascriptHandler
The IJavaScriptHandler interface acts as a helper service. The IJavaScriptHandler
interface parses WDK JavaScript files and changes parts of them in order to scope the
global variables and functions to the namespace of the generated web page, thus avoiding
naming 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 class
that 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 the
host environment. This should be used to ensure that WDK components adopt the look
and feel of the host environment and the user-selected theme in that environment. The
implementation of this interface maps a WDK style onto a portal style. By default, this
interface returns the WDK CSS style name unchanged.
Implemented by: Environment, AppServerEnvironment
Returned by: AbstractEnvironment.getThemeContract()
ILocale
The ILocale interface allows WDK to read the locale and time zone of the external
environment. If this interface is not implemented or its methods return null, WDK
will accept defaults from the Java Virtual Machine by calling the static methods
Locale.getDefault() and TimeZone.getDefault(). The JVM inherits these defaults from the
host environment.
Note: The method within this interface does not require a valid HTTP session to be
invoked.
Returned by: AbstractEnvironment.getLocaleContract()
ILifecycle
The ILifecycle interface handles lifecycle events. You can use these methods to initialize
session, request state, or call vendor-specific APIs to perform initialization or cleanup. A
Web 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 be
called within the bounds of a request start and end. For example, every environment
method will be called after a request start method and before a request end method.
Returned by: This interface is not returned.
ISession
The ISession interface allows you to integrate with the principal-based authentication
services provided by the J2EE host environment. The contract returns the strings
required 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.
Returned by: AbstractEnvironment.getSessionContract()
IContentTransfer
Caution: The IContentTransfer interface is deprecated for the 5.3 SP1 release. For the
5.3 SP1 release the content transfer mechanism is handled on an installation basis by
configuring the wdk/app.xml file.
The IContentTransfer interface provides a mechanism for configuring the content transfer
mechanism 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
Returned by: AbstractEnvironment.getContentTransferContract()

IMessageService
The IMessageService interface allows you to intercept messages that would otherwise be
destined for WDK’s error message service. For example, the PortalEnvironment class
implements handleError() to get an instance of the portlet session and, from it, the HTTP
session. The error is then saved as a session attribute.
Returned by: AbstractEnvironment.getMessageServiceContract()
IError
The standard J2EE error handling mechanism of a JSP page directive that specifies an
error page is not supported in the JSR-168 portal environment. The IError interface
overrides the errorPage JSP page directive and displays errors inline.
When an exception reaches the JSP page, the JSP container forwards to the intended
URL. If that URL is a JSP page, the JSP container makes the exception available to the
JSP page via an implicit object called exception. If the standard error page URL is not
acceptable for the target environment such as a portal environment, then the developer
can override this for all components by implementing getErrorUrl().
Some portal servers do not support forwarding at all, and the mechanism must be
overridden by implementing the onError() method. Like the error page, this method gets
the exception and the JSP Writer. Anything written to the Writer will produce results
inline, inside the actual Portlet content area itself. If the interface is not implemented or
returns null, the framework will return the standard error component URL as defined by
the installed Documentum application.
Implemented by: Environment, Jsr168Environment
Returned by: AbstractEnvironment.getErrorContract()
IInfo
The IInfo interface must be implemented by an environment class. This interface
defines a set of methods for returning version information about the environment
implementation itself and the external environment. Used by WDK logging.
Returned by: Environment.getEnvironmentInfo()

Registering an environment
Registering 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 se

ServletContextKeywords_beaportal=WebLogic Server
ServletContextKeywords_ibmportal=IBM WebSphere Application Server
ServletContextKeywords_sunportal=Sun Java System Application Server
ServletContextKeywords_standaloneportal=WDK Portlet Container
ServletContextKeywords_myportal=My Application Server
The example adds a client environment setting of myportal and a corresponding

application server information string of My Application Server.
2. Add an entry to the wdk/app.xml file within the serverenv element filtered for your
client environment:
</environment>
...
<serverenv>
<filter clientenv=’webbrowser,appintg’>
<class>com.documentum.web.env.app.AppServerEnvironment</class>
<preferencestoreclass>com.documentum.web.env.HttpPreferences</preferencestor
</filter>
<filter clientenv=’beaportal’>
<class>com.documentum.web.env.bea.BeaPortalEnvironment</class>
<preferencestoreclass>com.documentum.web.env.jsr168.Jsr168Preferences</prefe
</filter>
<filter clientenv=’ibmportal’>
<class>com.documentum.web.env.ibm.IbmPortalEnvironment</class>
</filter>
<filter clientenv=’sunportal’>
<class>com.documentum.web.env.sun.SunPortalEnvironment</class>
</filter>
<filter clientenv=’standaloneportal’>
<class>com.documentum.web.env.standalone.StandaloneJsr168Environment</class>
<preferencestoreclass>com.documentum.web.env.HttpPreferences</preferencestor
</filter>
<filter clientenv=’myportal’>
<class>com.documentum.web.env.myportal.MyAppEnvironment</class>
<preferencestoreclass>com.documentum.web.env.MyAppPreferences</preferencesto
</filter>
</serverenv>
</environment>

The example adds values for the location of the class and preferences files for the
client environment setting:
• client environment setting = myportal
• class file = MyAppEnvironment
• preferences file = MyAppPreferences
HTML post-processing
Post-processing modifies the HTML that is generated by a component immediately
before it is committed back to the client. Post-processing is performed for the supported
portal servers in their respective environment classes.
The HTML produced by WDK components is rendered in a format that is acceptable to
its environment. The ITag interface handles how certain HTML tags are rendered at a tag
level. 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 because
each Portlet makes up a part of a Portal page.
When a finer level of granularity is required, for example if you wish to modify the
source attribute of the <FORM> tagor the class attribute of the <DIV> tag, you should use
post-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
• TR
The IRender interface provides a mechanism for switching on post-processing. The
class associated with the environments is used to define which HTML tags are to be
processed. If you implement an environment that post-processes a response, then you
will implement one or more methods of the form rewriteXXXTag() where XXX is the
name of the HTML element. All of these methods must take one parameter of type
Tag, for example rewriteImgTag(Tag tag). You may use the Tag class, page 66 and the
Attribute class, page 66 to inspect or change attributes in the HTML tag immediately
before it is returned.
The renderStartTag(), renderTagBody() and renderEndTag() methods render portal
specific 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 methods
within the Tag class allow you to set the name of a tag and get and set any associated
attributes for a tag.
public final class Tag
{
//Public Instance Methods
public 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 get
and set values for an attribute. In addition, you can get and set the delimiter character
that will enclose the attribute when it is rendered.
public final class Attribute
{
//Public Instance Methods
public 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 extend
the PortalEnvironment class or one of its subclasses. Implement the IRender interface in
your environment class. The PortalEnvironment class already implements IRender as it
contains the following behavior:
Public Boolean postProcess()
{
Return true;
}

This example rewrites the class applied to the Table and Tr tags to ensure that any tables
rendered by a WDK component will use the CSS styles as defined by the MyEnvironment
environment. 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>
</tr>
</table>
The following MyEnvironment class extends the PortalEnvironment class so

post-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 as
myportalTable 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">
</tr>
</table>
The tables will now be rendered using the CSS styles defined by the MyPortal
environment.

Environment hooks
A hook is used to retrieve information from the environment. For example, WDK uses
the LocaleHook to get locale and time zone information.
There is one hook for every interface in the env package. The hook class marshals calls
made by WDK and ensures the safety of the calls. If an interface implementation does
not exist, or returns null, the hook returns a default value. If there is an implementation
then the hook makes the call and returns the result to the calling object. Hook classes will
always end with the word Hook.

Chapter 6
Customization 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. Conceptual
information for each customizable component is discussed in this chapter and customization
examples 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 layer

Documentum portlets use a customization layer that enable you to keep customizations
in a location separate from the installed product. This allows the custom layer to be
easily migrated after an upgrade or reinstallation.
All customized XML configuration and JSP files should be placed in the custom folder
within the application. This custom folder is treated as the top-level application layer
and overrides the functionality in any lower layers. This also makes it easier to preserve
customizations after product upgrades.
The directory structure of the custom layer is flatter than the application itself. The config
subdirectory holds all XML configuration files, extended from any other application
layer, with no subdirectories. The strings subdirectory holds all NLS properties files,
placed within /custom/strings/com/documentum/custom.

Table 6-1. Structure of the custom layer
Directory Contains
custom JSP files extended from any other
application layer (no subdirectory
structure)
custom/config XML configuration files extended
from any other application layer (no
subdirectory structure)
custom/strings/com/documentum/custom NLS properties files extended from any
other application layer (no subdirectory
structure)
custom/theme Contains any custom themes (branding)
that you create. Requires a subdirectory
structure. For more details, refer to Web
Development Kit Development Guide.
Custom Java classes are not located in the custom layer. They are located in the WEB-INF
directory of the application, with the directory structure matching the package. You
should place your custom classes in /WEB-INF/classes/com/your_ company_name. The
path 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 denition inheritances and overrides

You can customize a client application by extending client components. You can also
add your custom components to the existing client application. You can apply your own
corporate branding to your extended application and override default UI and error
message strings. When you extend a definition in a XML configuration file in your
application, any element that is defined in the custom definition will override that same
element in the definition that has been extended. If the element is not specified in the
custom definition, that element will be inherited from the component that has been
extended 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 preference

components 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 will
overwrite 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 add
a single element, in your extended definition you would have to repeat the entire list
of components plus add the one additional component.
For example, the portal_preferences component would look like:
<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>
</component>
</scope>
</config>
The one additional component is extraprefs_preferences.
What to customize
The WDK customization model supports customization of controls, components,
actions, and applications. Controls are customized through JSP tags or through XML
resource files. Components, actions, and applications are customized through XML

configuration files. You can modify the application to reflect your company’s business
processes and appearance.
The application customization model enables you to create a custom DocApp and
modify the application templates and files. An application DocApp contains all the
repository components you need to properly run the application. Application templates
provide the layout and other non-content related elements such as JavaScript code you
need to create a Web page.
Note: All customized XML configuration and JSP files should be placed in the custom
folder within the application. This custom folder is treated as the top-level application
layer and overrides the functionality in any lower layers. This also makes it easier to
preserve customizations after product upgrades. For more information on the custom
layer and its location, refer to The custom layer, page 69.
Applications
WDK applications have varying numbers of application layers: the WDK layer, the
webcomponent layer and the custom layer. A customized WDK application is a Web
client that configures and extends the components in the WDK and webcomponent
layers.
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 elements
Within 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. For
example, the webcomponent layer inherits its application definition from the WDK layer.
You configure an application in the application XML configuration file app.xml, which is
located in the root folder of each application layer.
Components
Components are built on top of the WDK infrastructure. The Component class is an
extension 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 delivering
the proper dispatch based on context. It uses the configuration service to find the proper
physical implementation.
A component comprises an XML configuration file used to define the combination of
layout (JSP page), behavior, and resource bundles available in the component. These
definitions may be scoped for different contexts. The XML configuration file also
prescribes the required parameters that must be passed to the component along with the
properties 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 changing
the component definition or the JSP pages associated with it. This allows a component to
provide 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 of

the UI that you want to modify. One of the difficulties is that many pages are displayed
by container components, which provide common layout and behavior for several
different 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 following
ways:
• 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 status
bar 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 the
application.
Once you have identified the component, you can look in the reference section of the
WDK manual (for the WDK, webcomponent, or Webtop layers) or this manual (for the
Web Publisher portlet layer) to get more information about it. If it is a container, the
reference documentation will have more information about which components are used
in that container. You can also get more information about the component’s definition by
looking 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 layers
by viewing the componentlist component at http://host_name:port_number/app_name/
component/componentlist. This component presents a display with the following
information:
• 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 methods
This information is extracted from the XML configuration file for that component, and
it presents a handy centralized location from which to view component definitions
for the application.
Determining which parts of the component to customize
Once you identify the component you want to modify, and which application layer
the component resides in, you should decide which parts of the component must 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 of the appropriate
development guide. The generic WDK components from the WDK and webcomponent
layers are included in the Web Development Kit Development Guide. The Portal specific
components are covered in the appropriate Portal Development Guide. If the
modification involves extending a component by extending or creating a new Java class,
you should follow the sections on customizing Java in the appropriate development
guide.
If you are changing behavior of a component, you should consider whether the behavior
encapsulates business logic and will be extended to other Documentum clients. If so, you
may want to consider creating a business object rather than building the logic directly
in a WDK component. For more information, refer to Web Development Kit and Client
Applications Reference Guide and Documentum Foundation Classes (DFC) Development Guide.
To ensure successful components and controls, refer to the development guidelines
within these manuals.

Actions
Actions associate user interface (UI) events such as menu selection with application
functions and are usually launched by a UI element such as a link, button, list item or
menu item, or by a repository operation.
An action consists of an action XML configuration file and an action class that
implements the action and determines whether a user can perform an action based on
preconditions. The action control on a JSP page, such as a menu item or link, is enabled if
the preconditions are met. You can configure actions in the action XML configuration
file 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 a
JSP tag library, which allows you to configure many aspects of the UI rendered as HTML.
Basic controls provide standard Web functionality, and repository-enabled controls
provide data binding, validation, and formatting. You can configure controls through
the 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 form
generates HTML form tags and maintains a model of the form state and browser history
on the server. A form can include other forms, but generally there is a one-to-one
correspondence between a form and a Web page. You can configure forms by changing
the form layout in the JSP page itself.
Events
Events are raised when the user makes changes to elements in a UI form. Events can be
handled on the client, by JavaScript event handlers, or on the server. You can configure
events in the JSP pages by specifying the event handlers as control tag attributes and
adding your custom client-side event handlers.

Branding
The branding service manages the UI look by themes, which incorporate images and
icons, 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 you
register your brand in the application XML configuration file app.xml. Users select a
theme 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, and
messages without any knowledge of Java. WDK supports localization (translation) of the
UI strings through national language support (NLS) lookup. Locales are specified in the
application XML configuration file app.xml. The localized strings are locale-specific. The
application uses the string for the user’s selected locale.
Customization process
This section discusses some guidelines for customizing. Before you begin a customization
project, you should understand how the directory structure is arranged (for information
on 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. Extending
components, 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 custom
layer, not to the original files as installed by the installer. For more information on
the custom layer and its location, refer to The custom layer, page 69.
• make changes that extend or implement the application’s Java code including
component and control classes
• add new components or controls to the application
• make changes that add custom Java classes to the application
• build new Web applications
Following 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 for
your IDE describes how to set the classpath for your Web application. You must
set the classpath to include WDK libraries in order to run or compile WDK-based
applications from within your IDE.
The Documentum Java libraries must be referenced in the J2EE server classpath
because they are outside of the Web application. The home directory must be
referenced in the J2EE server path because it contains native libraries. The installers
for WDK and its client applications set the J2EE server classpath and the path to the
Documentum home directory when you run the installer on the J2EE server host. For
more information, refer to Web Development Kit and Applications Installation Guide .
If your Java IDE does not include j2ee.jar (or some subset of it) in its library
directory, you must install it on your local system and reference it in your IDE
classpath. You must also reference all of the jar files that are installed by the
WDK installer to your DOCUMENTUM_HOME directory (default=C:\Program
Files\Documentum\shared).
Consult the documentation for your IDE for instructions on how to set up a deployed
Web application for development, debugging, and compilation. The tutorial Web
Development Kit and Applications Tutorial describes how to set up NetBeans, a free
J2EE IDE, to work with WDK.
• Create a custom layer
All customized XML configuration and JSP files should be placed in the custom
folder within the application. This custom folder is treated as the top-level
application layer and overrides the functionality in any lower layers. This also makes
it easier to preserve customizations after product upgrades. For more information on
the 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 application
layer the component resides in, you should decide which parts of the component
must 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 of
the appropriate development guide for that application layer. If the modification
involves extending a component by extending or creating a new Java class, you
should follow the customizing Java sections of the appropriate development guide.
If you are changing behavior of a component, you should consider whether the
behavior encapsulates business logic and will be extended to other Documentum
clients. If so, you may want to consider creating a business object rather than
building the logic directly in a WDK component. For more information, refer to Web
Development Kit and Client Applications Reference Guide and Documentum Foundation
Classes (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 all
of 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 in
subsequent 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 add
Documentum 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 Portlet
Sample code for these portlets can be downloaded from the Documentum developer
web site http://developer.documentum.com.

Customization Examples

Chapter 7
Linking To A Documentum Component
If the portal container supports hyperlinks, you can add a hyperlink in a non-Documentum
portlet that launches a WDK component. That component will be displayed in place of the portal
frameset. The following example adds a link to a Documentum component and, in the Documentum
component, adds a link back to the portal.
Example 7-1. Creating a hyperlink to a component

The following example adds a hyperlink within a generic portlet to the Documentum About
component:
<a href="component/about" target="_blank">About this portal</a>
The link is displayed within the portlet, just below the graphic, as shown below:

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 the
about component is displayed in that window. The portal window remains open for other portal
operations.
Example 7-2. Linking back to the portal

The following example adds a link within a Documentum portlet component JSP page that returns
the 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 or
components, 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 this
example has been changed to suit the portal.) If you are linking to additional components, your first
component 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 8
Converting The DQL Editor Component
To A Portlet
If you wish your WDK-based components to be displayed inline in the portal, with all of the
navigation, style, and preferences benefits that are provided by the portal, you must convert the
component 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 the
element <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 to Web 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 ignored
in the portal environment. For information on how to provide portlet help, refer to Adding portlet
help, page 30.
Tip: Give each control in your portlet components a unique name, because they will be rendered by
the portal container into a single HTML page.

Converting The DQL Editor Component To A Portlet
Example 8-1. Adding a portlet denition

In the following example, a portlet definition for the dqleditor component is added to the portlet
application 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 BEA
WebLogic 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 9
Creating A Simple Time Sheet
You can create a simple form that can be used as a time sheet. The following sections explain how to
create a portlet for time sheet.
Creating the time sheet portlet denition

Add a portlet definition in the portlet.xml file located in /WEB-INF/portlet.xml. The
entry 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>
</supports>
<portlet-info>
<title>Documentum Timesheet</title>
</portlet-info>
<preference>
<name>view</name>
<value>timesheet</value>
</preference>
<preference>
<name>edit</name>
</preference>
<preference>
<name>help</name>
<value>timesheet</value>
</preference>
</portlet>

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 the
WebLogic portal, you need to create the timesheet.portlet file with the following content
in /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.0
portal-support-1_0_0.xsd">
<netuix:javaPortlet
definitionLabel="DocumentumTimesheet"
description="My Timesheet" title="Documentum Timesheet"/>
</portal:root>
Creating the time sheet component denition

Create an XML configuration file timesheet_component.xml in /custom/config that
references your custom JSP page and class. Add the following content to the component
definition file:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<scope>
<component id="timesheet">
<pages>
<start>/custom/timesheet/timesheet.jsp</start>
</pages>
<class>com.mycompany.timesheet.Timesheet</class>
</component>
</scope>
</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 hours
for 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 classes

Create the Timesheet and TimesheetForm class files using your J2EE IDE, and instruct
your 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 the
form. 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 is
addressable 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 attribute
form 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;
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 10
Creating A Custom Type Object Grid
The drilldown portlet allows you to display all objects in a selected cabinet or folder. You may
want to display only a selected object type. For this purpose, use a portlet component that extends
the objectgrid component.
The following example creates a portlet that displays a custom object type, technical publications
web. 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 denition

Create a component configuration file, webdocs_component.xml, in /custom/config to define
your new component. This definition is a copy of the objectgrid component definition, with new
component JSP page, new component class, and two new columns:

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

<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>
</column>
<column>
<attribute>r_content_size</attribute>
<label><nlsid>MSG_SIZE</nlsid></label>
</column>
<column>
<attribute>a_content_type</attribute>
<label><nlsid>MSG_FORMAT</nlsid></label>
</column>
<column>
<attribute>owner_name</attribute>
<label><nlsid>MSG_OWNER_NAME</nlsid></label>
</column>
<column>
<attribute>group_name</attribute>
<label><nlsid>MSG_GROUP_NAME</nlsid></label>
</column>
<column>
<attribute>r_creator_name</attribute>
<label><nlsid>MSG_CREATOR_NAME</nlsid></label>
</column>
<column>
<attribute>r_object_type</attribute>
<label><nlsid>MSG_OBJECT_TYPE</nlsid></label>

</column>
<column>
<attribute>r_version_label</attribute>
<label><nlsid>MSG_VERSION_LABEL</nlsid></label>
</column>
<column>
<attribute>r_creation_date</attribute>
<label><nlsid>MSG_CREATION_DATE</nlsid></label>
</column>
<column>
<attribute>r_modify_date</attribute>
<label><nlsid>MSG_MODIFIED_DATE</nlsid></label>
</column>
<column>
<attribute>r_modifier</attribute>
<label><nlsid>MSG_MODIFIER</nlsid></label>
</column>
<column>
<attribute>r_access_date</attribute>
<label><nlsid>MSG_ACCESS_DATE</nlsid></label>
</column>
<column>
<attribute>r_lock_owner</attribute>
<label><nlsid>MSG_LOCK_OWNER</nlsid></label>
</column>
<column>
<attribute>tp_edition</attribute>
<label>Edition</label>
</column><column>
<attribute>tp_web_viewable</attribute>
<label>Publish?</label>
</column>
</columns>
</component>
</scope>
</config>
Note: When you add columns to the component definition, you must also add them to the JSP page in
order for them to be displayed.
Example 10-2. Creating the Webdocs portlet JSP page

The JSP page displays a grid of all objects of the custom type with sortable column links as well as a
properties link and an actions link for each document.
<%@ 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 object
ObjectGrid form = (ObjectGrid)pageContext.getAttribute(
ObjectGrid.FORM, PageContext.REQUEST_SCOPE);
DataProvider dataProvider = ((Datagrid)form.getControl(
ObjectGrid.GRID_NAME, Datagrid.class)).getDataProvider();
//label used on ’view’ link
String 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’>
datafield=’CURRENT’ mode=’numeric’/>
</dmf:celltemplate>


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


<dmf:celltemplate>
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’>
</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: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:datevalueformatter type=’short’>
<dmf:label datafield=’CURRENT’/>
</dmf:datevalueformatter>
</dmf:celltemplate>


<dmf:celltemplate>
<dmf:label datafield=’CURRENT’/>
</dmf:celltemplate>
</dmf:celllist></td>


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



<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 denition

You must also add a portlet definition in portlet.xml. The entry in /WEB-INF/portlet.xml looks similar
to the following:
<portlet>
<description>Documentum Web Docs</description>
<portlet-name>DocumentumWebDocs</portlet-name>
<supports>
</supports>
<portlet-info>
<title>Documentum Web Documents</title>
</portlet-info>
<preference>
<name>view</name>
<value>webdocs</value>
</preference>
<preference>
<name>edit</name>

</preference>
</portlet>
Note: You cannot create this portlet definition through the WebLogic Workshop IDE, because it will
overwrite the Documentum portlet class DocumentumComponent. Instead, add the definition to
portlet.xml with a text editor.
You must also add a portal-specific information as required by your portal server. For the WebLogic
portal, 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"
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 class

You referenced the webdocs component class in the webdocs component definition. Create
the 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 overrides
the query that supplies the data for the object grid. The internal attributes are supplied by the query
string 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 attributes
are supplied by the list of columns in the component definition.
The class contents are as follows.
package com.mycompany.webdocs;
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 in
DOCUMENTUM_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 11
Adding A Logout Portlet
You can add a logout portlet that logs the user out of all Documentum repositories while maintaining
the portal session. The following example creates a logout portlet.
Example 11-1. Creating the Logout portlet component denition

Create a component configuration file, logout_component.xml, in /custom/config that defines your
new 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>
</component>
</scope>
</config>
Example 11-2. Creating the Logout portlet JSP page

In the JSP page, there is a simple logout button and label. The button specifies an onclick event
handler in the logout component:
<%@ 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>

</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 similar
to the following:
<portlet>
<description>Documentum Logout</description>
<portlet-name>DocumentumLogout</portlet-name>
<supports>
</supports>
<portlet-info>
<title>Documentum Logout</title>
</portlet-info>
<preference>
<name>view</name>
<value>logout</value>
</preference>
<preference>
<name>edit</name>
</preference>
</portlet>
Note: You cannot create this portlet definition through the WebLogic Workshop IDE, because it will
overwrite the Documentum portlet class DocumentumComponent. Instead, add the definition to
portlet.xml with a text editor.
You must also add a portal-specific information as required by your portal server. For the WebLogic
portal, 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"
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 class

You referenced the logout component class in the logout component definition. Create
the 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 developer
Web site.)
package com.mycompany.logout;
import com.documentum.fc.client.IDfSessionManager;
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 in
DOCUMENTUM_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 is
the merging of the code with the main WDK code. The merging of the code allows the
developer to leverage a substantial amount of the WDK features in a Portal environment.
The Web Development Kit and Client Applications Development Guide is your primary
reference for these WDK features.
This section of the documentation describes features that are different from WDK for
portal environments. The section comprises:
• Chapter 12, Portlet Specific Components
• Chapter 13, Actions In A Portal Environment

Portlet Reference

Chapter 12
Portlet Specic Components
The component in this section is specific to WDK for Portlets and is not available to standalone
Web 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 in Web
Development Kit and Client Applications Development Guide.
Portlet specic components

There is only one Portlet specific component — portallogin.
portallogin
Prompts the user with a Please log in link and, when the link is clicked, displays the
login component. The login dialog is not displayed when the user’s full credentials
have been saved.
Parameters
startUrl URL to forward to. If a startURL is specified, the login
component will forward to that URL after successful login. This
value takes precedence over startComponent. The URL must be
relative to the root context, not relative to the directory location
of the current JSP page.
startComponent If an entry component name is specified, the login component
will forward to that component after successful login.

Portlet Specic Components
startPage This parameter sets the component page that will be displayed
on forward.
docbase Specifies the repository to log into.
For information on the types of application login, see the section on application login
and authentication in Chapter 3, Portlet Authentication.
Elements
Element Description
showoptions Allows you to hide (false) or display (true) the additional
login options. The additional login options are hidden
(set to false) by default.

Chapter 13
Actions In A Portal Environment
There are no specific actions in a Portal environment. Full details of how actions work is contained in
the Web Development Kit and Client Applications Development Guide.
However, there are a number of actions that are not supported, or their behavior is amended, within a
Portal 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 denition les

WDK amends the behavior of, or disables, a number of actions for Portal environments
using a number of action definition files:
• dm_smart_list_actions.xml, page 113
• generic_actions.xml, page 114
• room_actions.xml, page 114
The behavior of actions is amended or disabled by filtering on the client environment
element, <filter clientenv= ...>. The behavior is disabled by setting the <filter
clientenv=’not portal’ ...> and additional behavior is added by setting the <filter
clientenv=’portal’ ...>.
dm_smart_list_actions.xml
The 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>

<filter clientenv=’portal’>
<component>search</component>
<container>searchcontainer</container>
</filter>
</execution>
This code ensures that the Search Results component, search, is always opened within the
searchcontainer component. This means that the user will always have the functionality
associated with the searchcontainer component, most importantly the Close button.
This allows the user to close the Search Results component and return to the search
or advanced search component.
generic_actions.xml
The generic_actions.xml action definition file contains two actions that are disabled:
<action id=’newprocess’ nlsid=’MSG_NEW_PROCESS’ showifdisabled=’false’/>
</filter>
This disables the new workflow template action as this is not supported in Portal
environments.
<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 in
Portal environments.
room_actions.xml
The room_actions.xml action definition file contains the same actions as the
generic_actions.xml file.
Disabling actions using JSP les

WDK effectively disables actions for Portal environments by removing the controls
that initiate them from the UI. Controls are removed from the UI by setting one of the
following:
• <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 of

controls 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, that
are 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
A customize, 74
AbstractEnvironment class, 46 definition, 72
action model, 20
definition, 75 portallogin, 111
APIs UI, 73
environment, 51 content server, 18
application context
components, 74 introduction, 20
definition, 72 control
layers, 72 definition, 75
model, 21 custom layer
AppServerEnvironment class, 48 definition, 69
architecture inheritances and overrides, 70
Documentum stack, 16 structure, 70
WDK for portlets, 23 customize
attribute class, 66 component, 74
authentication guidelines, 76
J2EE, 34 overview, 69
manual, 33 process, 76
portlets, 33 what to customize, 71
saved credentials, 38 customize example
service, 18 converting component to, 85
single sign-on, 38 custom type grid, 95
skip, 39 link to component, 81
logout portlet, 105
B
BeaPortalEnvironment class, 49
D
BOF data access
service, 18 service, 18
branding definition
definition, 76 documentum portlet, 22
documentum portlet
what is, 22
C
class
inheritance diagram, 45
E
portlet styles, 28 encryption
portlets, 27 password tool, 35
component environment
converting to portlet, 85 configuration, 51

Index
hooks, 68 I
registering, 64 I18N
environment class, 44, 47 service, 18
AbstractEnvironment class, 46 IbmPortalEnvironment class, 50
AppServerEnvironment class, 48 IContentTransfer
BeaPortalEnvironment class, 49 environment interface, 62
environment class, 47 IError
IbmPortalEnvironment class, 50 environment interface, 63
Jsr168Environment class, 48 IInfo
PortalEnvironment class, 48 environment interface, 63
StandaloneJsr168Environment IJavascriptHandler
class, 51 environment interface, 60
SunPortalEnvironment class, 50 ILifecycle
environment interface, 51 environment interface, 61
IContentTransfer, 62 ILocale
IError, 63 environment interface, 61
IInfo, 63 ILogin
IJavascriptHandler, 60 environment interface, 52
ILifecycle, 61 IMessageService
ILocale, 61 environment interface, 63
ILogin, 52 inheritance
IMessageService, 63 class diagram, 45
IPreference, 53 installed
IRender, 59 portlet files, 22
ISecurity, 52 interfaces
ISession, 62 environment, 51
ISuperCredentials, 52 IPreference
ITag, 60 environment interface, 53
ITheme, 61 IRender
environments environment interface, 59
namespace, 29 ISecurity
overview, 43 environment interface, 52
preference mechanism, 53 ISession
event environment interface, 62
definition, 75 ISuperCredentials
environment interface, 52
F ITag
flags environment interface, 60
portlets, 41 ITheme
environment interface, 61
H
help
J
portlets, 30 J2EE
hooks application server, 18
environment, 68 authentication, 34
HTML post-processing, 65 security, 16
example, 66 JSP
page (forms) definition, 75
standard, 15

Index
JSR 168, 21 link to component, 81

JSR-168 login, 33
Jsr168Environment class, 48 logout, 105
namespace, 29
refresh, 30
L styles, 28
layer tracing, 41
environment, 44 troubleshooting, 41
locale UI, 28
login, 40 WDK architecture, 23
login writing, 27
J2EE principal, 34 post-processing
locale, 40 example, 66
manual, 33 HTML, 65
password encryption, 35 preference
portlets, 33 login, 39
preferences, 39 mapping, 58
saved credentials, 38 scope, 58
setting up J2EE principals, 36 user-level, reading, 54
skip authentication, 39 user-level, writing, 57
ticketed, 36 presentation model, 19
principal (J2EE) authentication, 34
M
max_sessions, 40 R
refresh
N data om a portlet component, 30
namespace portlets, 30
in portlets, 29 register
environment, 64
P S
password encryption, 35
portal saved credentials authentication, 38
environments, 43 scope
portallogin, 111 preference, 58
server
Portal JSR 168 server, 18
content, 18
PortalEnvironment class, 48
portal, 18
portallogin
service layer, 18
component, 111
portal, 111 servlets
portlet standard, 16
class, 27 session pooling
service, 19
class styles, 28
single sign-on
converting component to, 85
custom type grid, 95 authentication, 38
flags, 41 skip authentication, 39
help, 30 StandaloneJsr168Environment class, 51
styles
installed files, 22
portlets, 28
integrate WDK, 43

Index
SunPortalEnvironment class, 50 portlets, 28

user sessions, 40
user-level
T preference, 54, 57
tag class, 66
text strings
definition, 76 W
ticketed WDK
login, 36 environment layer, 19
tracing foundation technologies, 15
portlets, 41
troubleshooting
portlets, 41
X
XML configuration, 15
U
UI

WDK For Portlets 5.3 SP1 Development

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

WDK For Portlets 5.3 SP1 Development

Caricato da

Copyright:

Formati disponibili

Web Development Kit for Portlets

Version: 5.3 SP1

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

Chapter 2 Creating Documentum Portlets ............................................................. 27

Chapter 3 Portlet Authentication ........................................................................... 33

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

Web Development Kit for Portlets Development Guide 3

Chapter 5 Integrating with Portal Environments .................................................... 43

Chapter 6 Customization Overview ....................................................................... 69

4 Web Development Kit for Portlets Development Guide

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

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

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

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

Chapter 13 Actions In A Portal Environment ......................................................... 113

Web Development Kit for Portlets Development Guide 5

Figure 1–1. Documentum Web Architectural Stack ............................................................. 17

6 Web Development Kit for Portlets Development Guide

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

Web Development Kit for Portlets Development Guide 7

8 Web Development Kit for Portlets Development Guide

This guide is divided into three parts:

Web Development Kit for Portlets Development Guide 9

To customize WDK-based applications, you must be familiar with the above-mentioned

10 Web Development Kit for Portlets Development Guide

Web Development Kit for Portlets Development Guide 11

Revision Date Description

12 Web Development Kit for Portlets Development Guide

Web Development Kit for Portlets Development Guide 13

14 Web Development Kit for Portlets Development Guide

WDK foundation technologies

Web Development Kit for Portlets Development Guide 15

The Documentum web architectural stack

16 Web Development Kit for Portlets Development Guide

Figure 1-1. Documentum Web Architectural Stack

The application stack is described in the following topics:

Web Development Kit for Portlets Development Guide 17

Component Model, page 20

Documentum Content Server

J2EE Application or Portal Server

18 Web Development Kit for Portlets Development Guide

The DFC BOF places business logic in reusable components.

The WDK Environment Layer

Web Development Kit for Portlets Development Guide 19

• Help service, which delivers localized, context-sensitive help

20 Web Development Kit for Portlets Development Guide

What is JSR 168?

Web Development Kit for Portlets Development Guide 21

• Portlet requests and responses

What is a Documentum Portlet?

The following topics describe Documentum portlets:

22 Web Development Kit for Portlets Development Guide

WDK for Portlets architecture

Web Development Kit for Portlets Development Guide 23

Figure 1-2. WDK for Portlets Architecture

24 Web Development Kit for Portlets Development Guide

Web Development Kit for Portlets Development Guide 25

26 Web Development Kit for Portlets Development Guide

Documentum portlet class

Web Development Kit for Portlets Development Guide 27

Portlet user interface

28 Web Development Kit for Portlets Development Guide

Web Development Kit for Portlets Development Guide 29