AD108 Best Practices for Creating Portlets

with
IBM WebSphere Portlet Factory
Ruth Seltzer
Senior Engineering Manager
IBM WebSphere Portlet Factory
Westford, MA

Legal Notice and Attributions

IBM Corporation 2007. All Rights Reserved
The workshops, sessions and materials have been prepared by IBM or the session

speakers and reflect their own views. They are provided for informational purposes only,
and are neither intended to, nor shall have the effect of being, legal or other guidance or
advice to any participant. While efforts were made to verify the completeness and
accuracy of the information contained in this presentation, it is provided AS IS without
warranty of any kind, express or implied. IBM shall not be responsible for any damages
arising out of the use of, or otherwise related to, this presentation or any other materials.
Nothing contained in this presentation is intended to, nor shall have the effect of, creating
any warranties or representations from IBM or its suppliers or licensors, or altering the
terms and conditions of the applicable license agreement governing the use of IBM
software.

References in this presentation to IBM products, programs, or services do not imply that

they will be available in all countries in which IBM operates. Product release dates and/or
capabilities referenced in this presentation may change at any time at IBMs sole
discretion based on market opportunities or other factors, and are not intended to be a
commitment to future product or feature availability in any way. Nothing contained in
these materials is intended to, nor shall have the effect of, stating or implying that any
activities undertaken by you will result in any specific sales, revenue growth or other
results.

IBM, the IBM logo, Lotus, Domino, WebSphere, Workplace and Lotusphere are trademarks
of International Business Machines Corporation in the United States, other countries, or
both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United
States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.

Rapid Portlet Development for IBM WebSphere

Portal
WebSphere Portlet Factory is a dedicated
portlet creation environment for WebSphere
Portal that simplifies & accelerates the
development, deployment, maintenance and
reuse of custom SOA-based portlets including
SAP, Lotus Domino, PeopleSoft, Siebel and
Web Service portlets.

Automation

Change

Reuse

WebSphere Portlet Factory Key Concepts

Builder
An adaptive, reusable
component that
generates Java,
XML and JSP for
specific portlet
functionality

Profile
A set of parameters
that vary Builder inputs
to dynamically
generate unique
versions of the portlet

Model
A container of Builders

WebSphere Portlet Factory Conceptual

Overview

WebSphere Portlet Factory is a system for software

automation

Portlet Factorys model-based development paradigm

using Builders is different than other development tools
You specify the inputs that control code generation, instead of
manipulating code and application artifacts directly

The benefit of this approach is a high degree of automation

Techniques and best practices have been evolving over the
last several years of experience with this paradigm

Best Practices Topics

Creating a portlet using a service architecture
Creating multi-language applications
Debugging techniques
Performance
Choosing the right builder
Top 10 model development best practices
Q&A
(Bonus Slides - Sharing functionality across models, Managing
projects across a team)

Creating a Portlet Using a Service

Architecture
SOA builders in Portlet Factory make it easy to create separate
service provider and consumer layers

SQL Call

SQL Call

Service Operation

Service Operation

Portlet (Consumer) Model

Service Definition

Service Consumer

Service Provider and Consumer Models

SQL Provider Model

RDB

Benefits of Using a Service Oriented

Architecture
Separate back end and presentation development
Automatic support for service testing
Develop consumer (presentation) model without any back end
access, using stub service model

Reuse services in multiple presentation models

Easily transform data between back end schema and some other
schema

Switch between multiple implementations of a service interface

without changing consumer model

Creating a Portlet Using a Service

Architecture
Steps for creating a portlet:
Create service for data access:

Use data access builder (SQL, SAP, Domino, etc.) for back end access
Use Service Definition and Service Operation builders to create service
Can include multiple operations, data transformation, and custom processing
Note that this service can be reused across any number of portlets

Use high-level builder to create initial presentation based on service inputs and results:
Use builder such as View & Form
Forms and views are automatically generated from the schema by the Page Automation
capabilities
Fields are automatically laid out using customizable rules
Page Automation adapts automatically to schema or service changes

Customize application iteratively:

Add builders to create new application elements and to modify existing elements
Change builder inputs, for example to select different styles
Modify elements that control automation, such as page templates and Rich Data Definitions
SOA Samples: http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/samples/datasvc.html

1. Create a Service Model

getViewData()
This Domino View builder
generates access to back end
data and generates schemas
that describe the data
structures

readDocument()
updateDocument()

Domino
Database

This Service Definition builder

defines the overall service and
generates test pages and code

These Service Operation

builders add public operations
to the service and define field
mapping to back end data

getEmployeesByDept()
getEmployeeRecord()
updateEmployeeRecord()

2. Create the Initial Presentation Model

This Service Consumer builder

adds service metadata and
schemas, along with code for
calling the service

employeesGetEmployeesByDept()
employeesGetEmployeeRecord()
employeesUpdateEmployeeRecord()

This View & Form builder uses

schema information to create
pages for list, details, and
update, along with navigation
and supporting code

3. Customize the Presentation Model

This Data Column Modifier

builder hides and reorders
columns and adds sorting

This Rich Data Definition

builder controls all the
formatting, validation, display,
and editing of fields on all the
pages

Back End Data Support

Portlet Factory data access builders can be used to easily create
services

These data access builders create common elements used for

services:

Schemas
Data Service metadata that identifies the variables and methods for access
operations
Code for executing back end function

You can easily create your own custom builders to access

backends which are not supported out of the box. See a sample at
http://www.ibm.com/developerworks/websphere/zones/portal/portl
etfactory/samples/createbldrs.html for more information

SAP Function Call

SAP Function Call

Service Operation

Service Operation

Service Operation

Stub Service Model

Service Operation

Service
Mapping
Registry

Service Definition

Service Consumer Model

Service Consumer

SAP Service Model

Service Definition

Service and Stub Models

Schemas
Variables with
captured stub
data
Service Operation
methods

SAP

Creating Multi-Language Applications

Creating Multi-Language Applications

Models can support multiple languages/locales through the
use of:
Locale-specific resource bundles containing text or formatting
information (standard Java localization)
Locale-specific imported HTML layout pages
Only needed if layout pages contain locale-specific elements

Language and country are controlled using a profile set

that gets values from HTTP request or Portal

Creating Multi-Language Models

Use a Localized Resource builder at start of each model
Profile-enable the Language and Country inputs
Select the com.bowstreet.profileset.SimpleLocaleValues profile set
Use the LanguageCode and CountryCode inputs of that profile set

This makes the correct country and language values

automatically available to other builders
Any builders that bring in a resource bundle
Any builders that import HTML layout pages, such as Imported Page

Globalization sample: http://www.ibm.com/developerworks/websphere/

zones/portal/portletfactory/samples/misc.html

Debugging Techniques

Debugging Techniques
Look for builder errors and warning messages in Designer
Disable builders to simplify a model and isolate the problem
Use System.out.println in Action List or Java code
Use Java-level debugging
Can single-step and set breakpoints in generated or other code
Uses the remote Java debugging capabilities of Eclipse
See product help for details of how to set this up

Run with system tracing to see exactly what actions get executed
Look at generated code/pages

Performance

Some Common Causes of Performance

Issues
Poor performance of back end systems or services
Memory use and session data
Minimize use of large XML variables and session data

Lack of caching
Regen Profiling
For Edit mode in Portal, try to use execution profiling (specified in Profile
Set Entry). This avoids generating many different WebApps based on
personalization values

Built-in Performance Diagnostic Tools

System Tracing
Usually the quickest way to find the cause of a performance problem
Easily used when running from Designer
First column shows time (ms) spent in an action without children;
second column shows action with children

Server stats
A log file that periodically captures statistics about usage and
performance on a running server
See the WEB-INF/logs/serverStats.txt file in deployed WAR
Captures numerous statistics, such as request actions and their
latency and requests to external systems

Choosing the Right Builder

Choosing The Right Builder

Typical model development process:
Create data access, typically using a service
Use a high-level page pattern builder to create the initial portlet interface
Add builders to customize the portlet

See the Getting Started Guide and samples located at

http://www.ibm.com/developerworks/websphere/zones/portal/
portletfactory/proddoc.html for more information

Choosing Builders Creating Services

Task

Builder

Get access to data store

Use data access builder from following slide

Define the overall service

Service Definition

settings
Add an operation to a service

Service Operation

Generate a test harness for

Use the testing support inputs of Service Definition

testing a service

builder

Create a stub service model

In Service Definition builder, use the Generate Stub

button

Create a WSDL/SOAP service

In Service Definition builder, use the Generate WSDL

checkbox

Choosing Builders Data Access Builders

System or Data Source

Builder

Databases

SQL Call

Lotus Domino

Domino Data Access

Microsoft Excel

Excel Import

Java class

Linked Java Object

PeopleSoft

Peoplesoft Component Interface

SAP

SAP Function Call

Siebel

Siebel Business Component

Web Service

Web Service Call

XML Data

Variable or Import to XML

Choosing Builders Using Schemas and

Variables
Task

Builder

Create an XML variable

Variable

Use an existing schema

Use Schema builder to reference an existing XSD file

Use Variable builder to create a variable based on the
schema

Create a simple schema

Use Variable builder to create an XML variable with the

desired structure

Use Simple Schema Generator to make a schema from

Variable
Use an existing Java Bean

Linked Java Object

Java/XML Converter can be used to convert to XML

Transform data between

Use Service Operation builder for simple mapping

For more complex XML manipulation, use Java code that

schemas

manipulates IXml

Choosing Builders Creating the Initial

Portlet UI
Task

Builder

Access a service model

Service Consumer

Create initial portlet pages

View & Form

based on service data

Create initial portlet pages,
using back end-specific builder

Create a page with a graphical

Domino View & Form

SAP View & Form
PeopleSoft View & Form
Siebel View & Form
Imported Page and Web Charts

chart of data
Make a model available as a

Portlet Adapter

portlet
Add some structured data to a
page

Data Page

Choosing Builders Working With Columns and Data

Layout
Task

Builder

Hide columns in a table

Data Column Modifier

Rich Data Definition

Add sorting capabilities

Data Column Modifier

Reorder the columns in a table

Data Column Modifier

or add new columns

Add grouping to fields on a

Data Hierarchy Modifier

page
Create newspaper-style

Form Layout

columns for form data

Add buttons to expand and
collapse data by category

Category View

Choosing Builders Validation, Formatting, and

Field UI
Task

Builder

Format and validate data in

Rich Data Definition for maximum automation and

fields

centralized control

Data Field Modifier for individual fields in a model

Change the UI behavior for a
field (e.g., change to checkbox,

Rich Data Definition

Data Field Modifier

make read-only, or create a

link)
Create user-friendly labels for
fields

Data Column Modifier

Rich Data Definition

names; for example, display a

Lookup Table
Rich Data Definition (create Lookup from RDD XML file)
Apply a lookup table to pages with Data Field Modifier,

Department Name instead of

Select, Text, or Radio Button Group

Translate a set of internal

values into a meaningful

the Department Code

Choosing Builders Actions and Events

Task

Builder

Create a list of processing

Action List

actions
Assign a value to a variable

Action List (select Assignment under special actions)

Use some Java code

Linked Java Object

Method

Add portlet-to-portlet

Event Declaration and Event Handler (for simple events)

Cooperative Portlet Source and Cooperative Porlet

communication

Target (for Property Broker Events or Wired Portlets)

Add error handling to a portlet

Error Handler

Add caching to improve

performance

Cache Control
Service Operation builder has an option to add caching

Choosing Builders Navigation and Page

Actions
Task

Builder

Add action controls to a page

Button
Image Button
Link

Run an action when a form is

Form Submit Action

submitted
Run an action when a user

HTML Event Action

clicks or types on a page

Put pages onto separate tabs

Page Tabs

with navigation between tabs

Add paging controls to a portlet

Use the paging options in View & Form builder

Data Column Modifier with Paging Buttons or Paging
Links

Link to another Portal page

WebSphere Portal Link

Choosing Builders Controlling Page

Elements
Task

Builder

Show/hide an element based

on a condition

Visibility Setter

Set an HTML attribute for a

specified page element

HTML Attribute

Localize the text strings for a

portlet

Localized Resource
Use Data Page Localizer or the Resource Bundle input of

Insert one page in another

Inserted Page

Display some read-only text on

a page

Text

Add some client-side JavaScript

to a page

Client JavaScript

high-level builders to use resources text

Apply resourced text to other elements by referencing
the LocaleData variable

Choosing Builders Portal Integration

Features
Task

Builder

Integrate people awareness

or Sametime chat capabilities

People Awareness

Link to another Portal page

WebSphere Portal Link

Create a customizer for a

Use Portlet Customizer in a customizer model

Specify your customizer as a custom model choice in

business user or administrator

the Portlet Adapter builder of your portlet

Make a model available as a

Portlet Adapter

portlet
Retrieve user credentials from

WPS Credential

Credential Vault, to support

single sign-on with external
back end applications
Wire your portlets together and

Cooperative Portlet Source and Cooperative Porlet

communicate between them

Target

Choosing Builders Creating Rich Internet

Apps (Ajax, Dojo, etc) Builder
Task
Partial page refresh for a specific
action in your application

Use a builder which causes an action back to the model

Partial page refresh for a region

of your portlet

Ajax Region Builder

Create a REST-style service that

can be called by client-side
JavaScript

Call the method

Use client side events

Event Declaration Builder

Client Event Handler Builder

Enable Drag and Drop on your

page

Dojo Drag Source

Dojo Drop Target

Incremental client/server
validation as the user interacts
with a form

Dynamic Validation Builder

Other Ajax related builders to

explore

Ajax Type-Ahead, Dojo Enable, Dojo Inline Edit, Dojo

such as:
Form Submit Action Builder
Link Builder
Button Builder
Set the Post Action Behavior to Refresh specified page
location after running action

webAppAccess.getBackchannelActionURL(actionName,
false)
to create a URL to any model action that returns XML
That URL can be used by client code as a REST-style
service

Tooltip, Timed Action, Highlighter, Global Ajax Enablement,

XML/JavaScript Converter

Choosing Builders Sharing Model

Functionality
Task

Builder

Use some common builders in a

number of models

Imported Model

Reuse the actions or methods

of another Model

Linked Model

Include another model visually

on a page, with support for
navigation in the contained
model

Model Container

Top 10 Model Development Best Practices

Top 10 Model Development Best Practices

1. Use a service provider/consumer model architecture
2. Use the highest-level builder available for the job
3. Keep model size under 50 builders
4. Don't write lots of code in Method builder - use Linked
Java Object instead

5. Use Rich Data Definition to simplify and centralize field

formatting, validation, and UI

Top 10 Model Development Best Practices

6. Use "submit form" actions when updating server state and
"link" events for navigation

7. Use the Comment builder to mark and describe sections

of a model

8. Use Imported Model to include common elements needed

by multiple models, such as event declarations

9. Use Localized Resource Builder to get automatic

localization of resource bundles and imported pages

10.Use Run with system tracing option to examine

program flow and to look for performance issues

Lotusphere 2007 Related Sessions

1/22/2007
11:00am - 12:00pm

AD101 Lotus Software Development Tools Strategy and Road

map

1/22/2007
11:00am - 12:00pm

AD203 Rapidly Build Role-based, Customizable Dashboards

with IBM Workplace Dashboard Framework

1/22/2007
2:15pm - 3:15pm
Repeated: 5:00pm 6:00pm

AD104 Integrating IBM Lotus Domino into Your Portlets with

IBM WebSphere Portlet Factory

1/22/2007
4:30pm - 6:15pm

HND107 Building IBM Lotus Domino-Driven Dashboards and

Scorecards

1/23/2007
4:15pm - 5:15pm

ID404 Deploying a Business Scorecard and Dashboard with

SOA Web Services and IBM Websphere Portal

1/23/2007
4:15pm - 5:15pm

AD109 IBM WebSphere Portlet Factory: Advancing Beyond

Builders

1/24/2007
08:00am - 9:45am

HND109 IBM WebSphere Portlet Factory - Is it Really That

Simple? What are They NOT Showing Me?

1/24/2007
4:15pm - 5:15pm

BP303 Best Practices with IBM WebSphere Portal, IBM

Workplace Web Content Management, and IBM WebSphere
Portlet Factory

01/24/2007
5:45pm - 6:45pm

BOF206 Everybody's Talking about Dashboards What are the

Key Differentiators?,

Additional Information and Resources

WebSphere Portlet Factory Product Support Page
http://www.ibm.com/software/genservers/portletfactory/support/

WebSphere Portlet Factory Product Information Page

http://www.ibm.com/software/genservers/portletfactory/

DeveloperWorks Forums
http://www.ibm.com/developerworks/forums/wsdd_forums.jsp

WebSphere Portlet Factory Documentation, Samples and

Getting Started Guide on DeveloperWorks

http://www.ibm.com/developerworks/websphere/zones/portal/portletfa
ctory/proddoc.html

Meet the Developers Lab: Dolphin Asia 1

Q&A

Bonus Slides
There are several Best Practices that would not
fit into a one hour presentation. Information
about these Best Practices are available in the
following slides
Sharing functionality across models
Managing projects across a team

Sharing Functionality Across Models

Shared Automation Elements for Composite

Applications

Portlet Factory not only automates the construction of individual

portlets, but it can automate the generation of application
elements across portlets

There are a number of techniques for controlling the generation of

application elements in a central, shared way:
Rich Data Definitions
Data Page Templates
Imported Layout Pages
Imported Models
Profile Sets
Custom builders

With shared automation elements, customers can:

Provide single-point control of common functionality
Automatically give a large composite application a consistent look & feel
Dynamically change the entire applications look & feel
Enforce particular standards

Shared Automation Elements Rich Data

Definition

The problem:

Web applications need fine control of user interface for displaying and inputting data
Formatting, validation, change field behavior, etc.
This control of UI can be done using individual builders, but this results in duplicated
information across models

The solution:
Use Rich Data Definition (RDD) to control all aspects of field-level UI in a centralized,
automated way across models
RDD is attached to a schema, then generated pages automatically pick up behavior
RDD uses shared definition files

Example:
Using RDD, you can format every date field a certain way (i.e., MM/DD/YY), and use a
calendar picker when that field is editable

More Shared Automation Elements

Layout pages
These are HTML pages with named tag locations where JSP will be added
based on data schema
These are used to provide a common look and layout for generated pages

Data Page templates

These specify the detailed rules for generating HTML tags and styles for
data entry and display
Portlet Factory ships sample templates, and you can create your own

Imported Model
This builder works like #include in C/C++, with support for
parameterization
Used to include common elements in a set of models

Controlling Automation Across Models

Generated composite
application
Portlet 1

Models
Shared automation
elements
Rich Data Definitions
Data Page Templates
Imported Layout Pages
Imported Models
Profile Sets
Custom Builders

Builder 1
Builder 2
Builder 3
Builder 4

Builder 1
Builder 2
Builder 3

Portlet 2

Portlet 3

Builder 1
Builder 2
Builder 3

Managing Projects Across a Team

Managing Projects Across a Team

Use source code control such as ClearCase for project files
Models, HTML layout pages, Rich Data Definitions, properties files, Java
source, bdefs, schemas
Dont check in files that are part of Portlet Factory

Create Portlet Factory project in the local directory used for

source code control

Can check-in/check-out directly from project files

Standardize on folders for files within project