11

WDK Customization for Portals

Paul Warren, Andrew Jones – EngineeringJeff Spitulnik – Product ManagementSteve Byrnes – Education Services

2004 Developer ConferenceSan Ramon, CA

29 Sept 2004

Please note: A more recent version of this presentation may be available through the 2004 Developer Conference Website.

Please check there for updates.

22

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

33

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

44

Portal Architecture

55

Portal

� A “specialized” web application that provides value-added services such as

– Personalization– Single Sign-On– Content aggregation from various sources– Secure search facilities– Localization of content

� A Portal “page” represents a complete HTML document consisting of several Portlet components

66

Key Portal Functions

� Provides security and user management– Single sign-on/Authentication– Authorization and entitlements

� Provides information aggregation and integration– Filtering– Indexing– Classification– Automation– Syndication– Unified enterprise search

� Enables customization of pages by users

� Enables personalization (based on roles, profiles, context)

� Provides application integration– Single look and feel– Application interoperability– Process integration

� Administrators can either lock or open up areas of the page for end users to customize

� Unifies (or interconnects) enterprise infrastructure– Multiple repositories– Multiple communities– Single source collaboration,

authoring, & communication– Multiple enterprise

applications

77

Documentum Portal Integration Points

Enterprise Portals

Portal JSR 168 Interface / WSRP

W D K (JSP, XML, Java Class)

WP Portlets Search Cabinet Custom…Content Producer/Manager & Consumer Portlets

DFC (DQL)

Collaboration Portlets

eRoom Server

XML / XSLT

Authoring Tools

Publish

JSP/ ASP / XML, etc.

JDBC (SQL) Query

Publ

ish to

Porta

l JDBC Services

Site CachingServices

Content Consumer Portlets

Documentum Interfaces, Components, and Tools

Server Extensions

Content ServerContent Repository

Content Services

EDM

WCM

DAM

Compliance

Collaboration

Records Mngt.

Portals

ERP

CRM

Custom

ECI Services

SearchPortlets

ADK

Virtual RepositoryInternalExternal

88

WDK for Portlets Overview

� The Web Development Kit for Portlets installs– DFC– WDK Components and Configuration files– Portlet Definition, Configuration and Help files– Custom Classes and JAR files– JSP Tag Libraries

in a JSR-168 compliant portal server� WDK for Portlets runtime differs from the standalone runtime

– These differences are not exposed to customizations

� Guidelines for configuration and customization of portal and standalone environments are the same

99

WDK for Portlets Overview – Components

� Main common components (Documentum Portlets 5.2.5)– advsearchcontainer - categorydrilldown– drilldown - homecabinet_drilldown– inboxdrilldown - myobjects_drilldown– subscriptions_drilldown– workflowstatusdrilldown

� New portlet specific components, for example (5.2.5):– accessibleactions - portal_login– general_preferences - component_preference– portal_preferences - saved_credentials

1010

Documentum Portlets 5.2.5

� Cabinets� Home Cabinet� Recent Files� Subscriptions� Inbox� Workflows� Search & Advanced Search� Browse by CategorySupport for:� Login, Saved Credentials, User Preferences� Single Sign-On

1111

Documentum Portlets 5.2.5 (continued)

1212

Documentum Portlets 5.2.5 (continued)

1313

Documentum Portlets 5.2.5 - Home Cabinet Actions

1414

Documentum Portlets 5.2.5 - Advanced Search

1515

Documentum Portlets 5.2.5 - Edit Preferences

1616

Reference Implementations & Certifications

Sun Java System Web Server 6.1 Service Pack 2

Solaris 8 2/04, 9 4/04

Sun Java System Application Server 8 Update Release 1

Solaris 8 2/04, 9 4/04Sun Java Enterprise System Portal Q2 2004

WAS 5.0.2Red Hat Enterprise Linux 3.0 Update 2

WAS 5.0.2AIX 5L V5.1 ML6, V5.2 ML3

WAS 5.0.2Solaris 8 2/04, 9 4/04

WAS 5.0.2Windows 2000 Server SP4,Windows Server 2003 (32-bit version)

IBM WPS 5.0.2.2

WLS 8.1Red Hat Enterprise Linux 3.0 Update 2

WLS 8.1HP-UX 11, 11i v1

WLS 8.1Solaris 8 2/04, 9 4/04

WLS 8.1Windows 2000 Server SP4,Windows Server 2003 (32-bit version)

BEA WLP 8.1 SP3

Portal's App ServerPortal's Operating SystemPortal Server

Other certs could be completed by portal vendors: Plumtree, PeopleSoft, Tibco, ATG, CA.

Additional portal server ports under development by Documentum or third parties: Plumtree Corporate Portal, Oracle Portal, SAP Enterprise Portal, PeopleSoft Portal…

1717

Where is this all going?� Expected enhancements in 5.3:

– Usability and multidocbase support– Content transfer – WSRP support– Documentum Forms support– Collaboration portlets– Packaging and installation changes– Enhanced search– Expose more preferences, provide more end user control of component

behavior� Anticipated post-5.3 enhancements:

– Process management integration– Enhanced Documentum Forms support– Enhanced repository integration and enterprise search– Collaboration integration improvements– Taxonomy and metadata integration– Entitlement, user models, user management integration– “Inbox” unification– DCM/RM/RPM?

1818

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

1919

History

Jan 97 Jan 98 Jan 99 Jan 00 Jan 01 Jan 02 Jan 03 Jan 04 Jan 05Jan 1996 Jan 2006

Yahoo! launchMy Yahoo!

User pop. grows 50% in 3 mnths

Jan 97 Jan 98 Jan 99 Jan 00 Jan 01 Jan 02 Jan 03 Jan 04 Jan 05Jan 1996 Jan 2006

Pure play corporate portalsemerge; Plumtree, Epicentric, etc with easy URL based plug n’ play

App Server vendorsget on board; BEA, Sun,

IBM, Oracle, etc, java-based

WSRP v2.0

BEA WeblogicPortal 8.1 SP2

Draft WSRP

WSRP v1.0

JSR168 CommunityReview

JSR168 v1.0

2020

Portal Architecture • Portal Technology Overview• Portlet Technology• WDK for Portlets• WDK for Portlets Architecture

• Portal Technology Overview• Portlet Technology• WDK for Portlets• WDK for Portlets Architecture

�Portal Technology Overview• Portlet Technology• WDK for Portlets• WDK for Portlets Architecture

�Portal Technology Overview• Portlet Technology• WDK for Portlets• WDK for Portlets Architecture

2121

Portlet Container

� Portlets are deployed in a Portlet container that:– Provides a runtime environment for Portlets– Manages the life cycle of each Portlet– Provides persistent storage for storing Portlet preferences– Caches the portlets (some portal servers)– Receives requests from the portal to execute requests on the portlet

2222

Portlet Architecture

� Java technology based web component� Managed by a portal container� Generates a piece of markup called a “fragment”

– Adheres to certain rules such as no <html> tags, for instance– Fragment generated by a Portlet aggregates with that from other

Portlets to form a portal page– Fragment generated by a Portlet may vary from one user to another

depending on the user configuration

2323

What Does JSR168 Define?

� Portlet API– Portlet Requests– Preferences– User information– Security– Deployment packaging

� Portlet Container– Extension of servlet container

� Contract between portlet and container

2424

Similarity with Servlet

� Both are Java technology based web components� Life-cycle is managed by a specialized container

– Servlet by servlet container– Portlet by portlet container

� Both generate dynamic content� Both interact with web client via a request/response paradigm

2525

Differences with Servlet

� Portlets only generate markup fragments, not complete documents

� Portlets are not directly bound to a URL� Web clients interact with portlets through a portal system� Portlets have a more refined request handling

– action requests and render requests

� Portlets have predefined states– portlet modes– window states

� Portlets can exist many times in a portal page

2626

Integration Between the Two

� Attributes set in the portlet request are available in the included servlet request

� Attributes set in the portlet session are accessible from the servlet session and vice versa

� Portlet and the included servlet or JSP share the same output stream

2727

Portlet Interfacepublic interface Portlet

{

public void init(PortletConfig config) throws PortletException;

// Action Request: Invoked only when the URL is an

// action targeted to the portlet, it does not produce// output

public void processAction( ActionRequest request,

ActionResponse response)

throws PortletException, IOException;

// Render Request: Invoked on every request to the portal

// it produces output to create the portal page

public void render( RenderRequest request,

RenderResponse response)

throws PortletException, IOException;

public void destroy();

}

2828

Portlet Lifecycle

2929

Portlet Request Handling

3030

processAction()

3131

doView()

3232

doEdit()

3333

GenericPortlet Class

� Implements Portlet interface� Render()is like service() in Servlets, calls specified render

methods based on Portlet mode– doView() for View mode– doEdit() for Edit mode– doHelp() for Help mode– Is extended by portlet developers – Override render methods as necessary

3434

ExamplePortlet

import javax.portlet.*;public class ExamplePortlet extends GenericPortlet {

protected void doView(RenderRequest request,RenderResponse response)throws PortletException, IOException {PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher(“/view.jsp”);prd.include(request, response);

}protected void doEdit(RenderRequest request,RenderResponse response)

throws PortletException, IOException {PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher(“/edit.jsp”);prd.include(request, response);

}public void processAction(ActionRequest request,ActionResponse response)

throws PortletException, IOException {PortletMode mode = new PortletMode(request.getParameter(“mode”));response.setPortletMode(mode);

}}

3535

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

3636

What is WDK?

Application Environment

Application ConfigurationApplication Frameset Application Logic

Component Model

Component Definition

ActionDefinition

ConfigurationComponentDispatching

ActionDispatching

Layout(Presentation)

DataBinding

JSP 1.1/Servlet 2.2 Services

Behavior(App Logic)

Service Model

Model Registration /InteroperabilityI18N

HistoryMechanism

Authentication

Application

Application Server

Documentum Content Server

Session Pooling Data Querye.g. DFC/JDBC

BrandingEngine

ComponentCustomization

Versioning

Business ObjectsDCTMBehavior

HTMLPages

DCTM Components

DCTMApplications

LocaleEngine

ActionCustomization

Application Context

�Portal Technology Overview�Portlet Technology�WDK for Portlets• WDK for Portlets Architecture

�Portal Technology Overview�Portlet Technology�WDK for Portlets• WDK for Portlets Architecture

Server-sideControls

Server-sideEvents

Presentation Model

3737

What is a WDK Component?

Component

Component Definition(XML)

Behaviour(Java)

Layout(JSP)Layout

(JSP)Layout(JSP)

3838

What is WDK for Portlets?

3939

Environment Interfaces

Environment Interfaces

Locale Login

Error Messaging

TagRewritingPreferences

Rendering Credentials Theme

ContentTransfer

PageProcessing

4040

Environment Implementations

4141

Portlet

What is a WDK Portlet?

ComponentComponent Definition

(XML)

Behaviour(Java)

Layout(JSP)Layout

(JSP)Layout(JSP)

DocumentumPortletMethods:

doView doEdit doHelp processAction

portlet.xml

<portlet>

<user-attribute>

4242

Converting an Existing WDK Component

<portlet-app><portlet>

<portlet-name>MyNavPortlet</portlet-name><portlet-class>

com.documentum.web.env.DocumentumPortlet</portlet-class><expiration-cache>0</expiration-cache><supports>

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

</supports><portlet-preference>

<preference><name>view</name><value>drilldown</value>

</preference></portlet-preference>

</portlet></portlet-app> <portlet-app>

<user-attribute><description>Start Folder</description><name>app.start_folder</name>

</user-attribute></portlet-app>

<dmf:html><dmf:head>

<dmf:title>My Navigation Portlet</dmf:title><dmf:webform/>

<dmf:head><dmf:body>

<dmf:form><!-- controls -->

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

</dmf:html>

4343

Adding Preferences to your WDK Portlet

� Portlet Preferences– Accessed using standard Config Service getters and setters– Defined in Component’s Definition; i.e. drilldown_component.xml– Exposed through Portlet’s Component Prefs tab (EDIT mode)– Apply to a single instance of a Portlet only

� User Preferences– Accessed using standard Config Service getters and setters– Defined in Application Definition; i.e. app.xml– Also defined as <user-attribute> in portlet.xml– Exposed through General Prefs tab (EDIT mode)– Apply to ALL User’s Portlets

4444

Configuring Single-Sign On

� Edit AuthenticationSchemes.properties� Edit TrustedAuthentication.properties

– Use TrustedAuthenticator utility

� Set default value for application.authentication.docbase user preference

com.documentum.formext.session.AuthenticationSchemes.propertiesAuthentication_scheme.1=com.documentum.formext.session.UserPrincipalAuthenticationSchemeAuthentication_scheme.2=com.documentum.formext.session.SavedCredentialsAuthenticationSchemeAuthentication_scheme.3=com.documentum.formext.session.DocbaseLoginAuthenticationScheme

com.documentum.formext.session.TrustedAuthentication.propertiescs525ora.username=superusercs525ora.password=56T6XH69NSLO5UFSZ8cs525ora.domain=

4545

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

4646

Customization Best Practices - Tag Usage

� JSPs should contain HTML fragments only– Do not use the following HTML tags: <HTML>, <HEAD>, <TITLE> or

<BODY>

� Portlets contribute their content to a larger HTML page� Use the equivalent WDK tags <dmf:html>, <dmf:head>,

<dmf:title> and <dmf:body>– These tags are environment aware and render accordingly

4747

Customization Best Practices - Real Estate

� Design the component’s presentation to fit on a page with other portlets

� Avoid unnecessary layout elements– Focus the component’s view on pertinent information only

� Portlets with large real estate will “squeeze” other portlets off the screen and create large scrolling regions resulting in usabilityissues

4848

Customization Best Practices - Branding

� Use portal CSS classes or WDK mapped CSS classes� Maintain portlet look and feel when the portal theme is changed� If the component needs to be shared with other WDK applications

utilize theme mapping rather than using portal CSS classes

4949

Customization Best Practices - Accessibility

� Pages should be fully accessible� All JSPs should be fully enabled for keyboard-only control and

other assistive technologies – Use the ALT attribute with images to define descriptive text of

the image content – Use <LABEL> tags to associate labels with form input

controls, so that page readers will be able to associate promptswith inputs

– Do not use color alone to denote state or information

5050

Customization Best Practices - Namespaces

� All form elements must be referenced by name not index– i.e. cannot use form[0].x but form[‘drilldown’].x

� Namespace elements to avoid conflicts between like-named elements

– Remember portlet multiple instances per page

� Use the IRender.namespaceElement() to encode such resources with the portlet instance name

� HTML element names, Uri's, and JavaScript resources should be namespace encoded

5151

Customization Best Practices - JavaScript

� Minimize dependencies on JavaScript� WDK portlets depend on JavaScript, however the more JavaScript

used the more browser-dependent your portlet becomes– For performance WDK4Portlets includes 1 combined .js file ONLY

� Increased maintenance issues, the more of the page that is rendered using JavaScript

� Encoding issues to avoid name clashes with other portlets, server side easy, client side issues

5252

Customization Best Practices - Popups

� Do not use pop-up windows� Creating pop-up browser instances containing portlets can cause

the portal to lose track of your current state and cause problems � Other than using JavaScript prompts there is no safe way to spawn

pop-ups within the portal unless the new link takes you to an external page outside the portal

5353

Customization Best Practices - IFrames

� There are potential issues when using an IFRAME that you need to consider

– The IFRAME fills its content based on a URL. The URL must be addressable by the browser, which means the server that is the target of the URL must be accessible by the browser. (Not necessarily the case with portlets.)

– Not all browsers support IFRAMEs– If the content is larger than the IFRAME region, then

horizontal and vertical scrolling should be enabled to allow theuser to scroll through the embedded content

– Be careful of content which itself contains scrolling regions asit can be difficult to manipulate all scrolling regions to view all embedded content, causing usability problems

5454

Customization Best Practices – Servlet Features

� Do not set the character set encoding of the response� Do not set the HTTP headers on the response� Cannot use:

– <jsp:forward>– pageContext.forward()– request.getRequestDispatcher().forward()

� Use:– <jsp:include>– pageContext.include()– request.getRequestDispatcher().include()

5555

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

5656

Demo Overview

� Overview of the portal environment� Creating a portlet from a WDK component� Setting up principal authentication

5757

Objectives

� Portal Integration Overview� Portal/Portlet Technology Background� In-Depth Product Architecture� Customization Best Practices� Development Demonstration� Additional Information / Q & A

5858

For Further Information…

� Release Notes– Hardware/Software requirements– Known bugs (not comprehensive)– Limitations– Technical Notes

� Install guide– General installation guidance– BEA WLP, IBM WPS, Sun Java

System Portal� Java docs� Documentum Developer Site

– Sample code• Simple Search Portlet• Documentum EDM Dashboard• Adding Dynamic Data to a Portlet• Logout Portlet

� WDK and WDK Client Development Guide

– Portlet-specific content throughout (e.g. authentication, branding)

– Many areas apply to portlets as well (e.g. NLS, actionlist)

– Part 3: WDK for Portlets• What is a Portlet/Portlet Architecture• Environment Layer• Creating Portlets• Portlet Examples

– Part 5: Portlet Reference• Portlet Controls• Portlet Components

� Portlet End-User Guide and Online Help– Component exchange

� Community forums

5959