Front cover
WebSphere Portal Express
Customizing Portal Express for Small to Medium Business
Customizing your Portal Express
Environment to meet business needs
Using Lotus Component Designer
to build a custom component
Deploying applications
through templates
John Bergland
David Bowley
Adam Egressy
Stefan Neth
Stephen Renwick
ibm.com/redbooks
Redpaper
International Technical Support Organization
WebSphere Portal Express - Customizing Portal
Express for Small to Medium Business
October 2007
REDP-4316-00
Note: Before using this information and the product it supports, read the information in “Notices” on
page vii.
First Edition (October 2007)
This edition applies to WebSphere Portal Express Version 6.0.
© Copyright International Business Machines Corporation 2007. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
The team that wrote this paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Thanks to the following people for their contributions to this project . . . . . . . . . . . . . . . . . . . .x
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Chapter 1. Introduction to WebSphere Portal Express . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Overview of WebSphere Portal Express Version 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Overview of key features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 Understanding how Portal 6 Express can benefit your organization. . . . . . . . . . . . 5
1.2.2 Why you want to customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.3 The options for customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Skills required for making customizations in Portal Express . . . . . . . . . . . . . . . . . . . . . . 8
1.3.1 Configuring and administering the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.2 Customizing through development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4 Overview of sample scenario used throughout this paper . . . . . . . . . . . . . . . . . . . . . . . 9
1.5 Structure of this paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.6 Starting point for beginning customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2. Introduction to customization in WebSphere Portal Express . . . . . . . . . .
2.1 Overview of customizations to be accomplished in this chapter . . . . . . . . . . . . . . . . . .
2.1.1 Value to the developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.2 Value to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Introduction to the sample scenario used in this paper . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Scenario background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Starting point for beginning customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Starting with the intranet Jumpstart sites as a basis for customization. . . . . . . . .
2.4 Basic customizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.1 Planning the desired layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.3 Moving portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.4 Adding and removing portlets from pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.5 Adding, deleting, and hiding pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.6 Introduction to Web content management in Portal Express . . . . . . . . . . . . . . . .
2.5 Customizing the look and feel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 Themes and skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.2 Using the built-in themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.3 Using the built-in skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.4 Creating your own theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.5 More about CSS style sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.6 Changing the portal page help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.7 Removing sign-up links from the portal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.8 Configuring the mail and calendar portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
© Copyright IBM Corp. 2007. All rights reserved.
15
16
16
16
17
17
22
22
23
23
24
27
28
34
37
63
63
63
66
69
77
78
79
80
iii
2.6 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Chapter 3. Introduction to Lotus Component Designer . . . . . . . . . . . . . . . . . . . . . . . . 85
3.1 Overview of customizations to be accomplished in this chapter . . . . . . . . . . . . . . . . . . 86
3.1.1 Value to the developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.1.2 Value to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.2 Lotus Component Designer 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.2.1 Business value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.2.2 Developer audience for Lotus Component Designer . . . . . . . . . . . . . . . . . . . . . . 88
3.3 Concepts and terminology for Lotus Component Designer . . . . . . . . . . . . . . . . . . . . . 88
3.3.1 Explanation of the design elements shown in the Navigator. . . . . . . . . . . . . . . . . 91
3.4 Installing Lotus Component Designer and working with included sample applications. 94
3.4.1 Installing Lotus Component Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3.4.2 Launching Component Designer for the first time. . . . . . . . . . . . . . . . . . . . . . . . . 95
3.4.3 Installing sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
3.5 Modifying the contact list sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
3.5.1 Step-by-step: adding image resources to your application . . . . . . . . . . . . . . . . . . 99
3.6 Editing the contact list sample component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.6.1 Step-by-step: editing the ContactsView page . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.6.2 Step-by-step: editing the ContactDisplay page . . . . . . . . . . . . . . . . . . . . . . . . . . 110
3.6.3 Step-by-step: editing the ContactEdit page . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
3.6.4 Exporting the modified ContactList sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
3.7 Deploying modified ContactList sample to your portal server . . . . . . . . . . . . . . . . . . . 119
3.7.1 Step-by-step: creating a new deployment profile . . . . . . . . . . . . . . . . . . . . . . . . 119
3.7.2 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
iv
Chapter 4. Customization using Lotus Component Designer . . . . . . . . . . . . . . . . . .
4.1 Overview of custom application to be built in this chapter . . . . . . . . . . . . . . . . . . . . .
4.1.1 Value to the developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1.2 Value to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Preview of application components we2 build in this chapter . . . . . . . . . . . . . . . . . . .
4.3 Building the purchase ordering component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.1 Creating a new component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.2 Creating the purchase order main page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Creating the stock control component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.1 Preview of the stock component you will build . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.2 The Stock View page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.3 Incorporating Web services into the stock control system . . . . . . . . . . . . . . . . .
4.5 Adding Ajax to the purchase ordering system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1 Introducing Ajax usage within Lotus Component Designer. . . . . . . . . . . . . . . . .
4.6 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
129
130
130
130
130
133
133
137
158
158
159
175
191
192
198
Chapter 5. Customization using WebSphere Portlet Factory . . . . . . . . . . . . . . . . . . .
5.1 Overview of custom application to be built in this chapter . . . . . . . . . . . . . . . . . . . . .
5.1.1 Value to the developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.2 Value to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Introduction to WebSphere Portlet Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 Key features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2 Main concepts: builders, models, and profiles . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.3 Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
199
200
200
200
200
201
201
202
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5.3
5.4
5.5
5.6
5.7
5.8
5.9
The difference between Lotus Component Designer and WebSphere Portlet Factory 202
Creating a project in WebSphere Portlet Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Building a service provider to a relational data store . . . . . . . . . . . . . . . . . . . . . . . . . 206
Previewing your service provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Building a portlet that displays a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Deploying your chart portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Chapter 6. Inter-portlet communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1 Overview of custom application to be built in this chapter . . . . . . . . . . . . . . . . . . . . .
6.1.1 Value to the developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2 Value to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Building communication into your portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1 Setting up the chart portlet as a co-operative source portlet. . . . . . . . . . . . . . . .
6.2.2 Setting up the stock portlet as a co-operative target portlet . . . . . . . . . . . . . . . .
6.2.3 Configuring the Property Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
221
222
222
222
223
223
226
230
231
Chapter 7. Introduction to composite application framework and templates . . . . . .
7.1 Overview of customizations to be accomplished in chapter . . . . . . . . . . . . . . . . . . . .
7.2 Introduction to composite application framework and templates. . . . . . . . . . . . . . . . .
7.2.1 Explaining terminology and concepts of composite applications and templates.
7.2.2 Composite applications in Portal 6 family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.3 Template features and functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Creating and deploying templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.1 Portlets associated with templates and applications. . . . . . . . . . . . . . . . . . . . . .
7.3.2 Easy access fOr Portal Administrator to create a new template . . . . . . . . . . . . .
7.3.3 Steps to provide users with the ability to create application templates . . . . . . . .
7.3.4 Creating the template for our department application . . . . . . . . . . . . . . . . . . . . .
7.3.5 Template setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4 Creating applications from templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.1 Step-by-step: adding the application to a page. . . . . . . . . . . . . . . . . . . . . . . . . .
7.5 Templates from applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6 Applications and portal policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6.1 Introduction to portal policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6.2 How policies apply to composite applications . . . . . . . . . . . . . . . . . . . . . . . . . . .
233
234
234
234
235
237
238
238
239
239
243
244
246
250
251
254
254
255
Contents
v
7.7 Deploying templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Appendix A. Installation and configuration best practices. . . . . . . . . . . . . . . . . . . . .
Upgrading Portal Server from 6.0.0.1 to 6.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling LDAP security with the configuration wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sametime integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Domino Integration wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
265
266
267
267
267
Appendix B. Configuring the ITSOCOOL environment . . . . . . . . . . . . . . . . . . . . . . . . 269
Setting up a stock database in DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Installing and running a Web service to serve up supplier information . . . . . . . . . . . . . . . 275
Appendix C. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to get Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
281
281
281
281
281
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information about the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that does
not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not give you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of these programs.
© Copyright IBM Corp. 2007. All rights reserved.
vii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Redbooks (logo)
developerWorks®
i5/OS®
Domino®
DB2®
IBM®
Lotus Notes®
®
Lotus®
Notes®
Rational®
Redbooks®
Sametime®
System i™
Tivoli®
WebSphere®
Workplace™
Workplace Forms™
Workplace Web Content
Management™
The following terms are trademarks of other companies:
SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and in several other
countries.
Oracle, JD Edwards, PeopleSoft, Siebel, and TopLink are registered trademarks of Oracle Corporation and/or
its affiliates.
Java, JavaScript, JumpStart, JDBC, JSP, J2EE, and all Java-based trademarks are trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
Excel, Expression, Internet Explorer, Microsoft, SQL Server, Tahoma, Visual Basic, Windows, and the
Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
viii
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Preface
IBM® WebSphere® Portal Express Version 6.0 offers a new way for organizations with under
1,000 users and departments of larger organizations to be more productive, run their
businesses with greater speed and accuracy, and be more responsive to their customers.
IBM WebSphere Portal Express Version 6.0 helps you and your teams collaborate and share
documents, deploy and maintain Web sites, and access the applications, content, and people
you need to do your job with speed and accuracy. Integrated portal, document management,
Web content management, and collaboration capabilities all help better enable information
and application sharing. These key capabilities are provided in a single package that installs
in under an hour to help your organization gain industry-leading capabilities and help you
realize a faster return on investment.
Within this IBM Redpaper we focus on how your organization can customize Portal Express
to more effectively meet the needs of your organization. To provide a realistic business
context, we base our examples on a sample scenario using a fictitious company, ITSO
Cooling Corporation. Specifically, we show how to take advantage of the existing
out-of-the-box corporate intranet site, then customize the look and feel of the Portal to
address your business needs and specifically match your corporate identity. Next, we show
how take advantage of Lotus® Component Designer, which is included with Portal 6 Express,
to customize out-of-the-box templates, as well as show how to build and deploy a custom
component from scratch. In doing this, we also address the advantages of deploying portlets
through application templates, allowing for easy re-instantiation of applications and
department-specific content. Finally, we also demonstrate some capabilities of Portlet
Factory, using this tool to further enhance our custom application by incorporating additional
portlets.
The team that wrote this paper
This paper was produced by a team of specialists from around the world working at the
International Technical Support Organization, Cambridge, MA, USA.
John Bergland is a project leader at the ITSO Cambridge Center. He
manages projects that produce IBM Redbooks® about IBM and Lotus
Software products. Before joining the ITSO in 2003, John worked as an
Advisory IT Specialist with IBM Software Services for Lotus (ISSL),
specializing in Notes and Domino® messaging and collaborative solutions.
David Bowley is a consultant with e-Centric Innovations in Melbourne
Australia, and has been working with IBM technologies since 1999. David
specializes in the WebSphere Portal and Lotus Domino product range, and
is a regular contributor to several prominent IT magazines. This is David's
first Redpaper.
© Copyright IBM Corp. 2007. All rights reserved.
ix
Adam Egressy is a consulting IT Specialist for AdHoc Systems Ltd., an
IBM Business Partner company in the Czech Republic. In the last seven
years, his worked has focused on IBM Lotus Domino and IBM WebSphere
Portal. Adam was originally responsible for project development and now is
the leader of development teams working on products developed by AdHoc
Systems. His areas of expertise among IBM WebSphere and Lotus Domino
technologies include object-oriented techniques, Web technologies,
databases, Java™, and .NET.
Stefan Neth is a Senior IT Specialist in Germany working with IBM
Business Partners dealing with Lotus core products and the WebSphere
Portal family. He is the technical focal point for Lotus Products on System
i™ and promotes Lotus Component Designer in Germany. Before working
with IBM Business Partners, Stefan worked with IBM Software Services for
Lotus (ISSL), specializing in Notes and Domino application development,
especially in Web projects.
Stephen Renwick is a Software Developer on the Lotus Component
Designer Development team in Dublin. His key role on this team was in the
development and integration of all the controls used in Lotus Component
Designer. Before working on the Lotus Component Designer project,
Stephen was involved on the XForms tool, and also worked on the JWL JSF
team.
Thanks to the following people for their contributions to this
project
򐂰 Adam Ginsburg
򐂰 David Nixon
򐂰 Jane L. Wilson
򐂰 Jennifer Heins
򐂰 Peter Janzen
򐂰 Salvatore Mazzotta
򐂰 Michael Burati
򐂰 Thomas Beauvais
򐂰 Patricia Bechtol
򐂰 Prashant S. Kulkarni
򐂰 Hendrik Haddorp
򐂰 Sam Alexander
򐂰 Lea Medhurst
򐂰 Neil Ginsburg
x
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Become a published author
Join us for a two- to six-week residency program! Help write a book dealing with specific
products or solutions, while getting hands-on experience with leading-edge technologies. You
will have the opportunity to team with IBM technical professionals, Business Partners, and
Clients.
Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you
will develop a network of contacts in IBM development labs, and increase your productivity
and marketability.
Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us!
We want our papers to be as helpful as possible. Send us your comments about this paper or
other IBM Redbooks in one of the following ways:
򐂰 Use the online Contact us review Redbooks form found at:
ibm.com/redbooks
򐂰 Send your comments in an e-mail to:
redbooks@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
Preface
xi
xii
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
1
Chapter 1.
Introduction to WebSphere
Portal Express
IBM WebSphere Portal Express Version 6.0 offers a new way for organizations with under
1,000 users and departments of larger organizations to be more productive, run their
businesses with greater speed and accuracy, and be more responsive to their customers.
IBM WebSphere Portal Express Version 6.0 allows you and your teams to collaborate and
share documents, deploy and maintain Web sites, and access the applications, content, and
people you need to do your job with speed and accuracy.
IBM WebSphere Portal Express Version 6.0 contains integrated portal, document
management, Web content management, and collaboration capabilities. Tight integration
between these areas of functionality helps to better enable information and application
sharing. These key capabilities are provided in a single package to help your organization
gain industry-leading capabilities and helping you realize a faster return on investment.
Within this Redpaper, we focus on how your organization can customize Portal Express to
more effectively meet the needs of your organization. To provide a realistic business context,
we base our examples on a sample scenario using a fictitious company, ITSO Cooling
Corporation. Specifically, we show how to take advantage of the existing out-of-the-box
corporate intranet site, then customize the look and feel of the Portal Express to address your
business needs and specifically match your corporate identity. Next we show how to take
advantage of Lotus Component Designer, which is included with Portal Express Version 6.0,
to customize out-of-the-box templates, as well as show how to build and deploy a custom
component from scratch. In doing this, we also address the advantages of deploying portlets
through application templates, allowing for easy re-instantiation of applications and
department-specific content. Finally, we also demonstrate some capabilities of Portlet
Factory, using this tool to further enhance our custom application by incorporating additional
portlets.
© Copyright IBM Corp. 2007. All rights reserved.
1
1.1 Overview of WebSphere Portal Express Version 6.0
WebSphere Portal Express Version 6.0 is a powerful, yet flexible and easy to use portal and
collaborative solution for your business. It provides access to people, information, and
applications for everyone who interacts with your business. It can improve efficiency and
communication in interactions in all areas of your business:
򐂰 Within your organization
򐂰 With your partners
򐂰 With your customers
Improving Communication and Productivity
Within your organization
With your customers
With your partners
Content
Applications
People
Processes
Figure 1-1 How Portal Express can help your organization
More specifically, Portal Express Version 6.0 can provide these benefits in the following
ways:
򐂰 Within your organization:
– Improve efficiency and productivity of your staff.
– Provide a single access point to all the data an employee needs to do his job.
– Keep teams and employees connected with instant messaging and presence
awareness capabilities.
– Allows individuals and teams to work on documents using enhanced document
management capabilities that integrate with the tools you already use.
򐂰 Build better relationships with your partners, through integration with your business
processes.
Provide access to information and applications that are personalized for each partner to
help you and your partner be more productive.
򐂰 Increase loyalty with your customers:
– Provide information about your company to your customers.
– Easy to deploy your Web site and easy for your staff to keep up to date.
2
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
1.2 Overview of key features
WebSphere Portal Express Version 6.0 is based on Portal 6, but provides specific
enhancements to make it more suitable for small and medium businesses with up to 1,000
users. The following key features include:
򐂰 Designed for an out-of-the-box experience, with example Internet and intranet sites that
can easily be tailored to a customer’s specific needs. Figure 1-2 illustrates the intranet and
extranet example sites that install in under an hour.
Sample sites provided
out of the box
Figure 1-2 Intranet and extranet example sites
Chapter 1. Introduction to WebSphere Portal Express
3
򐂰 IBM Web Content Management functionality is included directly within WebSphere Portal
Express Version 6.0. This capability reduces implementation time and costs by placing
content creation and management firmly in the hands of content experts for author once,
publish everywhere control. The end result is that Web content can be kept more accurate
and updated more frequently. Figure 1-3 illustrates the Web Content Management Portlet
included with WebSphere Portal Express Version 6.0, which allows for access to Web
content management capabilities.
Figure 1-3 IBM Web Content Management Portlet
򐂰 Document management tools enable users to easily share, view, and organize files of all
types in a central location.
򐂰 Support for access to a wide variety of applications, including IBM Lotus Notes®,
Microsoft® Office, and Microsoft Windows® applications, lets your employees work with
the applications they know.
򐂰 Instant Messaging and presence awareness capability to provide users with the ability to
contact each other in the context of the work they are doing.
򐂰 WebSphere Portal Express Version 6.0 includes IBM Lotus Component Designer, an
innovative, easy-to-use, standards-based development tool that allows application
designers to easily create components for WebSphere Portal Express.
򐂰 Finally, WebSphere Portal Express Version 6.0 is based on the latest version of
WebSphere Portal and provides extended capabilities with support of WebSphere Portlet
Factory, IBM Workplace™ Forms, Workplace for Business Strategy Execution, and the
Workplace Dashboard Framework.
4
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Products included with WebSphere Portal Express Version 6.0
WebSphere Portal Express 6.0 provides all of the tools and capabilities you need right out of
the box. In particular, it provides both full Web Content Management capabilities and Portal
Document management capabilities packaged within the product. For Web content, this
allows you to easily customize, update, and more accurately control your Web content. The
document management tools enable users to easily share, view, and organize files of all
types in a central location.
For building custom components, WebSphere Portal Express also includes IBM Lotus
Component Designer, an innovative, easy-to-use, standards-based development tool that
allows application designers to easily create components. Table 1-1 lists the products and
capabilities bundled within the Portal 6 Express offering.
Table 1-1 Products included within WebSphere Portal Express Version 6
Produce name
Description
Portal Server
WebSphere Portal Server Version 6.0
Note - This includes:
򐂰 Document Management
򐂰 Web Content Management
Database
DB2® Express
LDAP Directory
Tivoli® Directory Server
Application Development
򐂰
򐂰
Collaboration
Lotus Sametime® Presence Awareness and
Instant Messaging
Lotus Component Designer
WebSphere Portal Factory run time
1.2.1 Understanding how Portal 6 Express can benefit your organization
When considering how Portal Express Version 6.0 can provide benefit to your organization,
begin by considering the following questions:
򐂰 How well are your employees collaborating today? What key challenges do you face?
򐂰 How would your organization benefit from a document management solution that provides
a better way for users to share, view, and organize files of all types, that also helps reduce
e-mail?
򐂰 How would your organization's productivity improve if your employees could access
applications, people, and other content via a single user interface?
򐂰 What if you could delegate administrative actions to users, helping reduce administrative
overhead?
How Portal 6 Express capabilities can improve productivity and
efficiency
Portal 6 Express capabilities can improve productivity and efficiency by:
򐂰 Single user interface for all the information they need.
򐂰 Share and save documents in a central location.
򐂰 Productivity improved through real-time collaboration using instant messaging and
presence awareness.
Chapter 1. Introduction to WebSphere Portal Express
5
򐂰 Portal Express can be installed on a single server, is easily deployed, and provides
pre-built Web sites.
򐂰 Provides easy access to existing mail and calendaring systems.
򐂰 Easy access to and integration with third-party systems.
򐂰 Easy to delegate responsibility to users, reducing the load on the administrator.
򐂰 Easy to roll out applications and train users with consistent platform and interface.
򐂰 Easy to build, deploy, and maintain Web sites using example Web sites.
򐂰 Included development tools accelerate customization of applications to an organization’s
unique needs.
򐂰 A solution based on industry standards that can grow as the company’s needs grow
without high maintenance, migration, and retraining of users.
1.2.2 Why you want to customize
As mentioned above, part of the Portal Express v. 6 value proposition is to help your
organization deploy the product quickly and easily. You can then build upon this
out-of-the-box experience to tailor the information, tools, and capabilities to best meet your
organization’s needs.
The simplified installation process and provided sample JumpStart™ Internet and intranet
sites ensure that you can get up and running quickly. Once you begin to customize the
information, the real benefits of IBM Portal Express v6 become even more apparent. The
emphasis of this paper is to show you how to customize your Portal Express v6 environment
to accomplish the following goals:
򐂰 Customize the look and feel of Portal Express v6 to match your company’s corporate
identity.
򐂰 Provide a single, consistent user interface that provides access to all of the information
users need.
򐂰 Use the included Web Content Management capabilities to more efficiently manage and
update specific Web content.
򐂰 Using the tools such as Lotus Component Designer and WebSphere Portlet Factory, you
can develop custom applications for greater productivity. Keep in mind that these
applications may be completely new applications, or may serve to simply present a new
unified user interface for an earlier application. For example, in Chapter 4, “Customization
using Lotus Component Designer” on page 129, we illustrate how to build an application
that facilitates inventory management and new customer orders. In the case of our
example, these are assumed to be applications providing a new user interface to earlier
applications. We also show how these applications consume a Web service for their
source of data.
򐂰 Finally, through customization of applications, as well as creating and deploying
application templates, users can appreciate the value of composite applications within
Portal Express Version 6.0. More specifically, within a single Portal Page user interface,
portlets can work together, sharing information and ultimately providing a more
comprehensive application and useful data for the user.
6
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
1.2.3 The options for customization
With IBM Portal Express v. 6, there are several options for how to customize the Portal
environment to suite your organization’s specific needs.
򐂰 First, and possibly most beneficial to small and medium businesses, Portal 6 Express
provides the flexibility and built-in capabilities for customization right out of the box. Basic
customization of the look and feel of the portal, as well as customization and management
of Web content, can be accomplished using just the Portal Express Version 6.0.
򐂰 Customizing using specific tools, such as Lotus Component Designer, IBM WebSphere
Portlet Factory, or ultimately Rational® Application Developer.
Each of these customization methods, along with specific details of how to use the tool to
build the sample application described in the scenario, is highlighted in a subsequent chapter
of this paper.
Description of tools available for Portal 6 Express customization
The tools available for Portal 6 Express customization are:
򐂰 Lotus Component Designer
Lotus Component Designer is a visual script-based development tool for Domino or
Microsoft Development shops looking to create composite applications for portal or rich
client1.
򐂰 WebSphere Portlet Factory
WebSphere Portlet Factory is a targeted portlet creation tool for developers looking to
rapidly create service-oriented applications that integrate enterprise data and services,
like SAP®, Oracle®, and Domino, into composite applications for portal or rich client2.
򐂰 Rational Application Developer
Rational Application Developer is an easy-to-use visual, yet granular development
environment for both portal and portlet applications that includes the ability to visually edit
themes, skins, and the layout of pages for portal sites, and to create and maintain portlets
by incorporating technologies such as J2EE™, Web Services, JSF, Ajax, and Struts with
simple drag-and-drop.
1
2
Rich Client Support Available in Q3 2007
Rich Client Support Available in Q3 2007
Chapter 1. Introduction to WebSphere Portal Express
7
Figure 1-4 illustrates the options of tools.
Portal Tool Options
Rational Application Developer
WebSphere Portlet Factory
Lotus Component Designer
Eclipse
y Platform
y JavaTM development tools (JDT)
y Web development tools (WTP)
y Data tools
y Team APIs to support CVS, ClearCase, others
Figure 1-4 Tool options for Portal Express customization
Keep in mind that each of these tools can also be used together. Each tool provides a unique
approach for creating portlets. Since each tool creates portlets they can obviously work
together at the portal layer, providing powerful composite applications that communicate and
adapt to business needs. The ability to create an application using multiple tools gives
companies flexibility in their development approaches and enables them to use the correct
tool for any particular part of a portal application.
Note: Within the scope of this paper, we only cover customizations using Lotus
Component Designer and WebSphere Portlet Factory. We do not focus on using Rational
Application Developer.
1.3 Skills required for making customizations in Portal Express
To work with WebSphere Portal Express, we recommend knowledge and skills in the
following areas:
򐂰 WebSphere Application Server administration
򐂰 WebSphere Portal Server configuration
򐂰 Specific development skills using a development tool such as Lotus Component Designer,
WebSphere Portlet Factory, or Rational Application Developer
򐂰 IBM Web Content Manager (WCM)
1.3.1 Configuring and administering the environment
To work with WebSphere Portal Express, you would ideally need to be familiar with basic
WebSphere Portal concepts and administration. WebSphere Application Server
administration skills are also highly desirable for the lower level configuration (LDAP, Domino
integration, and so on). Domino skills would be needed if linking to a Domino server.
8
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
1.3.2 Customizing through development
As we illustrate in Chapter 2, “Introduction to customization in WebSphere Portal Express” on
page 15, you can perform basic customizations using the tools and capabilities provided
directly within the product and without specific development knowledge. Once you wish to
move beyond the basic customizations, however, it is helpful to have skills in the following
areas.
To develop simple applications (lists of content, for example) for WebSphere Portal Express,
you could get by with basic WCM knowledge. For more advanced development you would
need knowledge of a particular tool (either LCD or WPF).
򐂰 DB2 knowledge is only really useful if you want to do back-end integration with DB2.
򐂰 Heavy Ajax knowledge is not really necessary if you are using LCD or WPF, but you need
to know what it is.
򐂰 JavaScript™ is required for LCD development.
򐂰 Java is not required (but is very useful) for WPF development.
򐂰 HTML is useful for both LCD and WPF.
1.4 Overview of sample scenario used throughout this paper
For the purpose of providing a realistic business context throughout this paper, we discuss
the customizations within Portal Express as part of an employee intranet site for the fictitious
company, ITSO Cooling Corporation.
ITSO Cooling Corporation (ITSOCOOL) is an air conditioning unit and cooling system
manufacturing and distribution company with approximately 500 employees, spread across
three distinct geographic different locations.
Note: Details of the scenario are described in much greater detail in 2.2, “Introduction to
the sample scenario used in this paper” on page 17.
How Portal 6 Express can help ITSO Cooling corporation
ITSO Cooling has chosen Portal 6 Express to improve employee collaboration and boost
productivity.
򐂰 Rather than working with many disparate systems, Portal 6 provides a single user
interface for all the information they need.
򐂰 Employee Productivity is improved through real-time collaboration using instant
messaging and presence awareness.
Finally, using the Lotus Component Designer, ITSO Cooling has been able to quickly build
and deploy a new application the Portal 6 intranet that ties into both the order entry systems
and inventory management system. For members of sales/customer service, this application
provides greater ease of use for entering and monitoring the status of orders. For members of
the inventory management/order fulfillment team, this application provides a more efficient
way to monitor inventory levels and enter new stock items quickly and accurately.
Chapter 1. Introduction to WebSphere Portal Express
9
Figure 1-5 illustrates a preview of the ITSO Cooling intranet portal. Details of how these
customizations are implemented in much greater detail can be found in Chapter 2,
“Introduction to customization in WebSphere Portal Express” on page 15.
Customized portlet placement with
department specific information
Customized pages, allowing employees to
access specific information/applications
they need
Figure 1-5 Overview of the customized ITSO Cool intranet home page
10
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
1.5 Structure of this paper
This paper begins with an overview of the benefits and features of WebSphere Portal Express
Version 6.0, then provides step-by-step instructions on how to customize the Portal Express
environment and use specific tools to build and modify components and applications to more
effectively meet your organization’s needs. The approach taken was to begin by using the
out-of-the-box JumpStart intranet site as a starting point, and then customize from there
forward. Figure 1-6 illustrates the approach taken throughout this paper, while the next
section discusses each chapter’s objectives in greater detail.
Roadmap to the chapters in this Redpaper
1
Features and
Benefits of
Portal
Express 6
2
Basic
Customization
– Value
– Modifying /
proposition
adding /
removing
– Features
portlets
– Required
– Web Content
skills
Management
– Intro to
– Modifying
scenario
look and feel
via themes
and skins
3
Introduction
Lotus
Component
Designer
– Installing
LCD
– Intro to
concepts
– Customize
LCD
Templates
4
5
Customization
Using Component
Designer
6
Customization
Using Portlet
Factory
– Building
– Build
component
reporting
for order
portlet
entry
– Display
– Building
chart
component
populated
for inventory
from DB2
management
– Consuming
web services
Inter-Portlet
Communication
– Using
Property
Broker and
wiring
– Communicat
ion between
order portlet
and
inventory
chart
7
Composite
Application
Framework /
Templates
– Explain
concepts,
terms
– Integration of
document
manager
– Combining
components
and portlets on
a page
– From template
to application
Fictional scenario – ITSO Cooling Co.
Figure 1-6 Roadmap to chapters in this paper
Our objective is to provide the definitive guide on how to customize the environment and to
illustrate the flexibility of WebSphere Portal Express Version 6.0.
򐂰 Chapter 2, “Introduction to customization in WebSphere Portal Express” on page 15,
introduces some of the basic concepts and methods involved in customizing WebSphere
Portal Express. By the end of the chapter you will know how to perform several common
portal customizations, and understand how to manipulate the look and feel of portal pages
to fit the unique demands of your business.
򐂰 Chapter 3, “Introduction to Lotus Component Designer” on page 85, provides an
introduction to the basic design elements and concepts within Lotus Component Designer.
It shows how to install the sample applications coming with LCD, then guides you through
a scenario illustrating how easy it is to change the look and feel of components to match
your corporate identity. In this example we customize the contact list sample application to
change the look and feel to meet the corporate standards of our fictional TSO cooling
Chapter 1. Introduction to WebSphere Portal Express
11
company. Once the component customization is complete, we show how to deploy it on
the portal page.
򐂰 Chapter 4, “Customization using Lotus Component Designer” on page 129, shows how to
create custom components using Lotus Component Designer. More specifically, it first
shows how to create a simple purchase ordering component, which allows the sales
department to document each order taken. This component is created using the standard
method of data storage known as the docDB. Next, the chapter shows how to create a
stock control component, which uses other data sources, such as Web services, and a
relational data base. Finally, the chapter finishes by showing how to use the information
entered by the stock control component to assist when creating an order, using Ajax.
򐂰 Chapter 5, “Customization using WebSphere Portlet Factory” on page 199, builds upon
the ITSOCOOL scenario and discusses an example of how WebSphere Portlet Factory
might be used to further customize WebSphere Portal Express. Using WebSphere Portlet
Factory, it illustrates how to build a reporting portlet for the warehouse manager. This
portlet displays a chart populated from a DB2 relational data store. Finally, it also
discusses how to build a service provider in WebSphere Portlet Factory, which acts as an
intermediary between the chart and DB2.
򐂰 Chapter 6, “Inter-portlet communication” on page 221, demonstrates how ITSOCOOL can
set up communication between portlets in WebSphere Portal Express. The stock portlet
(built with Lotus Component Designer in Chapter 4, “Customization using Lotus
Component Designer” on page 129) and the chart portlet (built with WebSphere Portlet
Factory in Chapter 5, “Customization using WebSphere Portlet Factory” on page 199) are
used to illustrate how this is done. Within this example, the approach is to use the
WebSphere Property Broker and to configure the communications line (the wire) between
the orders portlet and the chart portlet.
򐂰 Chapter 7, “Introduction to composite application framework and templates” on page 233,
illustrates the concepts and benefits of this technology. This chapter explains the
terminology behind composite applications, then illustrates in a step-by-step manner how
to create a new template containing pages, portlets, and a component, all of which are
included in Portal Express for free. Specifically, this chapter builds upon the following
steps toward arriving at a composite application:
– It makes use of the sample applications from Lotus Component Designer and the
announcement portlets, and links portlets from WCM.
– It shows how to integrate the portal document manager within Portal Express to store
documents.
– Finally, once the template is complete, we then deploy an application based on this
template and show the steps that need to be done to customize access and content to
meet the needs of the targeted audience.
򐂰 Appendix A, “Installation and configuration best practices” on page 265, describes some
best practices that help you to install, upgrade, and configure your portal server. This
appendix is not a replacement for the installation, upgrading, or configuration sections of
the InfoCenter. It is intended only to supplement the information center, as it provides you
with hints and best practices on how to succeed quickly.
򐂰 Appendix B, “Configuring the ITSOCOOL environment” on page 269, discusses how to
configure your environment for the ITSOCOOL scenario discussed throughout this paper.
The following areas are covered:
– Setting up a stock database in DB2
– Installing and running a Web service to serve up supplier information
12
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
1.6 Starting point for beginning customizations
The emphasis of this book is on how to perform customizations within IBM WebSphere Portal
Express Version 6.0. This book intentionally does not focus on the installation and
configuration of Portal Express. For the latest and most comprehensive information about
how to install and configure Portal Express Version 6.0, we recommend that you refer to
Portal Express Version 6.0 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
This said, we do provide hints and tips for installation and on how to upgrade your Portal 6
Express environment from Version 6.0 to Version 6.0.1 in Appendix A, “Installation and
configuration best practices” on page 265. Refer to this appendix for help in installing,
configuring, and updating your environment.
Chapter 1. Introduction to WebSphere Portal Express
13
14
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2
Chapter 2.
Introduction to customization in
WebSphere Portal Express
This chapter introduces some of the basic concepts and methods involved in customizing
WebSphere Portal Express. To follow through with the examples in this chapter, you do not
need any software other than WebSphere Portal Express. By the end of the chapter you will
know how to perform several common portal customizations, and understand how to
manipulate the look and feel of portal pages to fit the unique demands of your business.
The customizations in this paper are discussed in the context of an employee intranet portal
for the ITSOCOOL air conditioning unit manufacturing company. The ITSOCOOL scenario is
introduced in this chapter, and throughout this paper you will see how ITSOCOOL can
leverage the customization capabilities of WebSphere Portal Express to improve the usability
of their portal site, and ultimately increase employee productivity. Although the examples in
this paper are based around the ITSOCOOL scenario, you will easily be able to apply and
develop the same customizations in your own environment.
Important: In addition to the specific customizations we demonstrate within this paper, you
can also get more in-depth information about customizing WebSphere Portal Express from
the InfoCenter at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/inst_req60.html
© Copyright IBM Corp. 2007. All rights reserved.
15
2.1 Overview of customizations to be accomplished in this
chapter
In this chapter we use the default intranet portal provided with WebSphere Portal Express as
a starting point for developing the ITSOCOOL company intranet site. The default intranet
portal gives you a predefined set of pages and portlets out of the box that you can use
immediately after installing portal. A default internet portal called the Internet JumpStart site
also comes packaged with WebSphere Portal Express. You could use the default internet
portal (called Internet JumpStart) as your baseline for customization if it is more appropriate
to your business, or even start a new portal from scratch.
Over the course of this chapter the following basic customizations are performed:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Renaming a page
Changing a page’s launch menu icon
Changing the default page opened when users log in
Moving portlets
Adding and deleting portlets
Adding, deleting, and hiding pages
Editing site content
Adding site content
Removing site content
Creating new content
Changing themes/skins
Customizing your portal logo
Changing the portal page help
Removing sign-up links from the portal
Changing style sheets
Configuring the mail and calendar portlets
2.1.1 Value to the developer
In the context of the ITSOCOOL scenario, developers will learn how to perform basic
customizations in WebSphere Portal Express, without requiring the use of a development tool
such as Lotus Component Designer or WebSphere Portlet Factory. By the end of this
chapter, developers will know some of the fundamental building blocks used for portal
customization, and be familiar with the Web Content Management tool used for adding,
editing, and removing content from WebSphere Portal Express.
2.1.2 Value to the user
During the course of this chapter the default intranet portal offered in WebSphere Portal
Express is gradually modified to suit the needs of the ITSOCOOL manufacturing company.
By the end of the chapter you will see how you can customize your own portal to provide an
environment for users that better suits the need of your business. Even the simple
customizations covered in this chapter, such as adding portlets and pages, changing
corporate logos, and updating themes and skins, can greatly improve the usability of your
site, and ultimately improve users’ experiences with the portal.
16
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2.2 Introduction to the sample scenario used in this paper
For the purpose of providing a realistic business context throughout this paper, we discuss
the customizations within Portal Express as part of an employee intranet site for the fictitious
company, ITSO Cooling Corporation. We refer to ITSO Cooling Corporation as ITSOCOOL.
2.2.1 Scenario background
ITSO Cooling Corporation is an air conditioning unit and cooling system manufacturing and
distribution company with approximately 500 employees, spread across three distinct
geographic different locations. In addition to having employees placed in different locations,
ITSO Cooling has several different divisions, each with a very specific focus.
For the sake of this scenario, we are interested in two specific groups:
򐂰 A sales/customer service group, which focuses on taking orders and providing excellent
customer service to all customers
򐂰 An inventory management group, which is responsible for maintaining stock in the regional
warehouses and for fulfilling customer orders.
Business need for the intranet portal
In order to gain a more competitive advantage in the marketplace and distinguish themselves
from their competition, ITSO Cooling has developed a strategy to improve in the following
areas:
򐂰 Provide the best customer service in the industry. In order to succeed at this,
communication between the Inventory management/fulfillment team and the
sales/customer service teams needs to be excellent. At any time, when a customer wishes
to knows the exact status of her order, the customer service representative needs to have
the latest information available.
򐂰 Improving overall inventory management in an effort to maintain minimal inventory levels
and to provide Just in Time (JIT) delivery. By reducing the levels of inventory on hand and
improving overall efficiency in the order fulfillment process, ITSO Cooling will significantly
reduce their operating costs.
How Portal 6 Express can help ITSO Cooling corporation
ITSO Cooling has chosen Portal 6 Express to improve employee collaboration and boost
productivity.
򐂰 Rather than working with many disparate systems, Portal 6 provides a single user
interface for all the information they need.
򐂰 Employee productivity is improved through real-time collaboration using instant
messaging and presence awareness.
򐂰 Finally, using the Lotus Component Designer, ITSO Cooling has been able to quickly build
and deploy a new application the Portal 6 intranet that ties into both the order entry
systems and inventory management system. For members of sales/customer service, this
application provides greater ease of use for entering and monitoring the status of orders.
For members of the inventory management/order fulfillment team, this application
provides a more efficient way to monitor inventory levels and enter new stock items
quickly and accurately.
Chapter 2. Introduction to customization in WebSphere Portal Express
17
About the ITSOCOOL intranet portal
ITSO Cooling has deployed Portal 6 Express and customized the out-of-the-box corporate
intranet JumpStart site to more accurately meet their needs. Specifically, the following
customizations help ITSO Cooling to meet their objectives:
򐂰 Adding/deleting/moving portlets to present the most relevant information to the users.
򐂰 Customizing the look and feel of the Portal (modifying Portal themes and skins) so that it
matches the corporate identity.
򐂰 Adding Portal Pages that serve as an access point for critical applications (order entry and
inventory management).
򐂰 Adding collaborative portlets, allowing for better communication in real time.
򐂰 Using templates to deploy and re-instantiate applications with department-specific
information.
Figure 2-1 illustrates a preview of the ITSO Cooling intranet portal. Throughout the remainder
of this chapter, we explain how these customizations were accomplished.
Customized portlet placement with
department specific information
Customized pages, allowing employees to
access specific information/applications
they need
Figure 2-1 Overview of the customized ITSO Cool intranet home page
18
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Figure 2-2 illustrates the new order entry user interface, allowing customer service
representatives a more efficient way to enter orders and monitor the status of existing orders.
Details of how this component is built using Lotus Component Designer are provided in
Chapter 4, “Customization using Lotus Component Designer” on page 129.
New Order Entry User Interface, allowing customer service representatives to
quickly enter orders and view stock levels
As an adjacent portlet, customer service representatives can access the
discussion database to view and discuss customer issues
Figure 2-2 Overview of the purchase order management portlets
Chapter 2. Introduction to customization in WebSphere Portal Express
19
Figure 2-3 illustrates a quick overview of the stock management center application.
Figure 2-3 Stock management center application
20
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Finally, within the MyDepartment tab (Figure 2-4) we illustrate the benefits of deploying an
application via a template, allowing for easy re-instantiation. The details of how this is built are
described in Chapter 7, “Introduction to composite application framework and templates” on
page 233.
Department specific data, easily deployed through
re-instantiation of the application using templates
Figure 2-4 Template instantiation
Chapter 2. Introduction to customization in WebSphere Portal Express
21
2.3 Starting point for beginning customizations
The emphasis of this paper is on how to perform customizations within IBM WebSphere
Portal Express Version 6.0. This paper intentionally does not focus on the installation and
configuration of Portal Express. For the latest and most comprehensive information about
how to install and configure Portal Express Version 6.0, we recommend that you refer to the
Portal Express Version 6.0 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
This said, we do provide hints and tips for the installation and on how to upgrade your Portal 6
Express environment from Version 6.0 to Version 6.0.1 in Appendix A, “Installation and
configuration best practices” on page 265. Refer to this appendix for help in installing,
configuring, and updating your environment.
2.3.1 Starting with the intranet Jumpstart sites as a basis for customization
Rather than trying to build a custom Portal site from scratch, it is much easier to begin with
the provided JumpStart sites then customize this going forward.
IBM WebSphere Portal Express Version 6.0 is designed for an out-of-the-box experience,
with example Internet and intranet sites that can easily be tailored to a customer’s specific
needs. Figure 2-5 illustrates the intranet and extranet example sites that install in under an
hour.
Sample sites provided
out of the box
Figure 2-5 Intranet and extranet example sites
Throughout this chapter, we show how to build customizations working from the
out-of-the-box intranet JumpStart sites.
22
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2.4 Basic customizations
In the following sections, we provide you with information about how to begin making
step-by-step basic customizations within your environment.
Important: For the sake of an illustrative example in this paper, we perform the
customizations while logged in as an administrative user (wpadmin) having the highest
level of access rights to the system.
In an actual production environment, you would not simply use full administrative rights for
all changes and customizations. Instead, you need to work with the Portal administrator to
determine necessary access rights and permissions to perform the changes required.
Within the scope of this Redpaper, we do not cover Portal administration. Instead, refer to
the Administering section of the Portal Express Information Center at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
2.4.1 Planning the desired layout
Figure 2-6 illustrates the planning for placement of portlets during the customization of the
home page. The value in this is to force thoughts and planning in advance about the
placement of content, and to determine on which pages specific content and portlets will
reside.
Home
Work
Collaboration
Orders / Inventory
My Department
Leading News Story
People Finder
Announcements Portlet
Reminder Portlet
Other News Items
(Industry and Local)
Essential Links
Figure 2-6 Planning for placement/inclusion of portlets
Chapter 2. Introduction to customization in WebSphere Portal Express
23
2.4.2 Getting started
In this section we discuss getting started.
Renaming the intranet JumpStart page
In this section we use the intranet JumpStart page provided with WebSphere Portal Express
as a starting point for developing the ITSOCOOL company intranet site. The intranet
JumpStart site is used because it already contains some of the functionality ITSOCOOL
requires for their portal, which will also be an intranet site.
The intranet JumpStart page will load by default when starting WebSphere Portal Express.
Take some time to browse around the site and look at some of the portlets offered by default.
You can always return to the intranet JumpStart site by clicking Launch → Intranet
JumpStart, as shown in Figure 2-7.
Figure 2-7 Default intranet JumpStart site
Once you are ready to begin customizing the intranet Jumpstart site for ITSOCOOL, the first
thing you should do is rename the default intranet JumpStart page so that the page is more
easily identifiable with ITSOCOOL when accessed through other menus or pages.
To rename the intranet JumpStart page:
1. Log in to the portal as an administrator.
2. Navigate to the administration page by clicking Administration at the bottom of the portal
or by clicking Launch → Administration.
3. Click Manage Pages under the Portal User Interface heading.
4. Click Content Root in the Manage Pages portlet.
24
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5. Click the Edit Page Properties icon next to the intranet JumpStart page, as shown in
Figure 2-8.
Figure 2-8 Edit the page properties
6. Enter in a new name for the intranet JumpStart site. We use ITSOCOOL, as shown in
Figure 2-9. Click OK when finished.
Figure 2-9 Renaming the intranet JumpStart site to ITSOCOOL
The intranet JumpStart page should now appear as ITSOCOOL in the Manage Pages portlet,
and also appears as ITSOCOOL when accessed from the launch menu.
Changing the ITSOCOOL launch menu icon
You can change the icon of the ITSOCOOL page as it appears in the launch menu by setting
the page property options.
To change the icon of the ITSOCOOL page:
1. Log in to the portal as an administrator.
2. Navigate to the administration page by clicking Administration at the bottom of the portal,
or by clicking Launch → Administration.
3. Click Manage Pages under the Portal User Interface heading.
4. Click Content Root in the Manage Pages portlet.
Chapter 2. Introduction to customization in WebSphere Portal Express
25
5. Click the Edit Page Properties icon next to the ITSOCOOL page to bring up the
ITSOCOOL properties window.
6. The icon section of the properties defines the graphic file used for the ITSOCOOL icon
displayed in the launch menu. This file is usually stored in the icons\page folder under the
directory holding your portal theme. By default, this is stored in the following folder:
[APPSERVER_ROOT]\profiles\wp_profile\installedApps\[CELL_NAME]\wps.ear\wps.war\
themes\html\Express\icons\page
Where [APPSERVER_ROOT] is the root directory of your WebSphere Portal Express
installation, and [CELL_NAME] is your WebSphere Portal Express cell name. If you are
unsure what your cell name is, navigate through the directory tree through Windows
Explorer to find the appropriate name.
To change the ITSOCOOL icon, upload a custom GIF file to this directory and point the
icon section of the properties portlet to the new graphics file, as shown in Figure 2-10. You
can use the current icon, intranet.gif, as a starting point (this file is also located in the
icons\page folder), or you can download the ITSOCOOL icon (available as a download see Appendix C, “Additional material” on page 279, for information about how to download
this information). Click OK when finished.
Figure 2-10 Icon section of the properties portlet
7. Log out of the portal and then log back in to see the updated icon.
The ITSOCOOL page will now display the custom ITSOCOOL icon when accessed from the
launch menu (Figure 2-11).
Figure 2-11 Display the custom ITSOCOOL icon
26
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Changing the page loaded by default when logging in
The ITSOCOOL entry will automatically load in the portal by default, because it is the first site
that appears under the content root section of your portal navigation tree. When you add new
pages to your portal, they appear at the end of the launch menu by default, and so will not be
the first thing that the user sees when logging in to the portal. It is often desirable for the page
you create to appear by default after logging in to the portal. Although we do not do this for
the ITSOCOOL example, we describe the steps required should you decide to use an
alternative page to the ITSOCOOL page for your default welcome page.
To open an alternative page by default when logging in to the portal:
1. Log in to the portal as an administrator.
2. Click Administration from the Launch menu.
3. Click Manage Pages under the Portal User Interface heading.
4. Click Content Root.
5. Reposition the entry of the page you would like to move by clicking the icon to the right
of the entry until it appears at the top of the navigation tree. You can rearrange pages in
the hierarchy by using the and
icons to the right of each entry.
All users will now see the repositioned page by default when they log in to the portal.
2.4.3 Moving portlets
Rearranging portlets in WebSphere Portal Express is an easy way to quickly customize your
corporate portal site. For the ITSOCOOL site we demonstrate how to move the Frequently
Asked Questions (FAQ) portlet to a more prominent position on the Work tab.
To move the FAQ portlet:
1. Log in to the portal with an administrator.
2. Click the Work tab.
Chapter 2. Introduction to customization in WebSphere Portal Express
27
3. Click the title bar of the FAQ portlet at the bottom of the page (you may have to scroll
down depending on your screen resolution) and drag it over to the top left-hand side of the
page, keeping your finger on the left mouse button. The title bar will not appear until you
move the cursor over it (title bars are located at the top of each portlet). Orange bars will
appear on the page, showing you where you can drop the portlet. When the orange bar
turns dark you have moved the portlet into a valid position on the page, and can release
the left mouse button. The page should reload and display the FAQ portlet in the top
left-hand corner of the portal, as shown in Figure 2-12.
Figure 2-12 Displaying the FAQ portlet in the top left-hand corner of the portal
Note: Any user with privileged access or higher to a portal page will be able to drag and
drop portlets on that page.
2.4.4 Adding and removing portlets from pages
Portlets can be added and removed from pages to customize the user’s experience with
WebSphere Portal Express. Users with privileged access (or higher) to a page can add and
remove portlets to that page, so that next time they log in to the portal their previous portlet
layout will be saved. Administrators can add and remove portlets to pages in order to set
standard layouts for all users. In this section we remove the recent news portlet from the
ITSOCOOL home page for all users, as we will use the news portlet displayed in the middle
column for our news instead. We also remove the disclaimer portlet included with WebSphere
Portal Express, as this is not appropriate for ITSOCOOL users. We then add a reminder
portlet, which administrators can use to set reminders for ITSOCOOL staff, and a weather
portlet, which accesses a Web service to return temperatures for user or administrator
specified locations. Later in this chapter, you will see how to use the calendar PIM portlet to
link your portal to an external server (such as Lotus Domino) to give more tightly integrated
reminder functionality.
28
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Note: You can prevent users from removing portlets from a page by either setting a user’s
access to the page to user, or by setting a user’s access for specific portlets to user.
Removing portlets
Although there are a number of ways to remove the recent news portlet from the home page,
the easiest way is as follows:
1. Log in to the portal as an administrator.
2. Move the cursor over the portlet title bar for the recent news portlet. A small arrow should
appear in the top right-hand corner of the portlet, as shown in Figure 2-13. Note that some
portlets might not automatically display a colored bar over the portlet title, but you can still
get the arrow to appear by positioning the cursor over the top of the portlet. If an arrow
does not appear, then you do not have access to delete the portlet, and you should make
sure that you are logged in to the portal as an administrator.
Figure 2-13 A small arrow should appear in the top right-hand corner of the portlet
3. Click the arrow icon in the top right-hand corner of the recent news portlet to open the
portlet menu.
4. Select Delete from the portlet menu, and then click OK when prompted to delete the
portlet.
Note: Removing a portlet only removes the portlet from the page, and does not actually
delete or uninstall the portlet. You can still add a portlet back to a page at any time by
dragging and dropping from the portlet from the portlet palette.
The recent news portlet should no longer be visible.
To delete the disclaimer portlet:
1. Log in to the portal as an administrator.
2. Move the cursor over the portlet title bar for the disclaimer portlet in the bottom right-hand
corner of the window.
3. Click the arrow icon in the top right-hand corner of the disclaimer portlet to open the portlet
menu.
4. Select Delete from the portlet menu, and then click OK when prompted to delete the
portlet.
Chapter 2. Introduction to customization in WebSphere Portal Express
29
The disclaimer portlet should no longer be visible.
Adding the reminder portlet
To add the reminder portlet to the ITSOCOOL portal:
1. Log in to the portal as an administrator and click Portlets in the top right-hand side of the
page to open the portal palette, as shown in Figure 2-14.
Click Portlets
Figure 2-14 Opening the portal palette
2. When the portal palette loads, type Reminder into the search box and click the
button.
3. When the reminder portlet appears in the portlet palette, click and drag it onto the page
underneath the people finder portlet. The orange bar underneath the people finder portlet
turns dark orange when you have moved the reminder portlet into a valid position on the
page.
Note: If your screen resolution is low, you might not be able to drag the reminder portlet
to the far right column directly, as the portlet palette might cover the last column. To get
around this, you can drag the reminder portlet into the middle column first, hide the
portlet palette, then drag the Reminder portlet over to the far right of the window.
4. Once you have added the portlet, click Portlets again to hide the portlet palette.
30
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Your portal should now look like the portal shown in Figure 2-15.
Figure 2-15 Adding the reminder portlet
The reminder portlet will now be visible on the ITSOCOOL home page. To set reminders in
the reminder portlet:
1. Click Edit Shared Settings from the portlet menu (you can bring up the portlet menu by
moving the cursor over the portlet title bar until the small down arrow appears in the top
right-hand corner of the portlet, and then clicking this arrow).
2. Click the plus sign (+) next to bring up the add reminders window.
Chapter 2. Introduction to customization in WebSphere Portal Express
31
3. Enter in some reminder text for your reminder. You can set additional parameters on this
page as well, such as a priority and due date. The settings we entered are shown in
Figure 2-16. Click OK when you are finished.
Figure 2-16 Setting parameters for the reminder portlet
4. Click Done on the reminder portlet to return to the reminder list.
The Reminder portlet should now show the new reminder (Figure 2-17).
Figure 2-17 New reminder
Adding the my weather portlet
To add the my weather portlet to the ITSOCOOL portal:
Important: The my weather portlet is only offered as a 30-day trial with WebSphere Portal
Express.
1. Log in to the portal as an administrator and click Portlets in the top right-hand side of the
page to open the portal palette.
2. When the portal palette loads, type My Weather into the search box and click the search
button
.
3. When the my weather portlet appears in the portlet palette, click and drag it onto the page
underneath the reminder portlet. The orange bar underneath the reminder portlet turns
dark orange when you have moved the weather portlet into a valid position on the page.
4. Once you have added the portlet, click Portlets again to hide the portlet palette.
32
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
We also configured some of the weather locations displayed on the my weather portlet to be
more relevant to ITSOCOOL users. To change the default weather locations in the my
weather portlet:
1. Open up the portlet menu for the my weather portlet by clicking the arrow icon in the title
bar of the my weather portlet and select Edit Shared Settings.
2. In the my weather settings panel, you can enter the names of the cities you would like to
add to the list in the Add a city box. You can also delete current entries from the list, move
entries up and down the list, and display temperatures in either fahrenheit or celsius. The
settings we used are shown in Figure 2-18.
Figure 2-18 My Weather portlet settings page
3. Click OK to save your changes.
Chapter 2. Introduction to customization in WebSphere Portal Express
33
Your portal should now look similar to the portal shown in Figure 2-19.
Figure 2-19 Portal Express home page with reminder portlet and my weather portlet added
2.4.5 Adding, deleting, and hiding pages
You can add and delete pages in WebSphere Portal Express from the Manage Pages section
of the Administration page. Pages are essentially containers for portlets, and are an excellent
way to navigate through a site at a high level. In this section we describe how to add an
orders page and an inventory page to the ITSOCOOL site, which is used in later chapters to
build a composite application for the ITSOCOOL scenario. We also demonstrate how to hide
the work page, as the portlets contained on this page are not strictly relevant to ITSOCOOL.
Although we do not actually delete any pages from the ITSOCOOL portal, we describe how to
do this should you decide to remove any pages.
Adding a page
To add an orders page and an inventory page:
1. Open the administration page by clicking Administration.
2. Click Manage Pages under the Portal User Interface heading.
3. Click Content Root in the Manage Pages portlet.
4. Click ITSOCOOL.
34
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5. You are now looking at the top level pages of the ITSOCOOL portal. Click the New page
button to bring up the Page Properties dialog.
6. Enter the title Orders for your portlet and click OK. You should now see an Orders entry in
the Manage Pages portlet.
7. Click the New page button to bring up the Page Properties dialog.
8. Enter the title Inventory for your portlet and click OK. You should now see an Inventory
entry in the Manage Pages portlet.
When you navigate back to the ITSOCOOL site by selecting it from the launch menu, your
portal should now have the same series of tabs as shown in Figure 2-20.
Figure 2-20 Modifying the series of tabs
Hiding a page
There are several ways in which you can remove pages from the ITSOCOOL site. The first
method is to hide the page so that it is no longer visible. This can be done on a per-user
basis, or for all users of the page.
To hide a page from all users:
1. Open the administration page by clicking Administration.
2. Click Manage Pages under the Portal User Interface heading.
3. Click Content Root in the Manage Pages portlet.
4. Click ITSOCOOL.
5. Click the active status indicator for the work page (see Figure 2-21) to make the work
page inactive.
Figure 2-21 Making the work page inactive
The work page will now be hidden from all users. You can display the work page again by
clicking the status indicator on the manage pages portlet to change the status back to active.
Chapter 2. Introduction to customization in WebSphere Portal Express
35
To hide a page from a particular group of users:
1. Log in to the portal as an administrator.
2. Open the administration page by clicking Administration.
3. Open the manage pages portlet by clicking Manage Pages under the Portal User
Interface heading.
4. Click the key icon next to the page that you want to modify the access levels for (see
Figure 2-22). In this example we demonstrate how to hide the work page from users who
are not in the wpsContentAdministrators group (this is something you might do if you want
to temporarily hide a page while it is being constructed).
Note: A page or portlet marked as inactive is not displayed in the portal, regardless of
the access level settings on the page or portlet itself.
Figure 2-22 Modifying the access levels
5. When you have clicked the access level icon, the resource permissions portlet will display.
The resource permissions portlet lets you set several different security levels for users and
groups. For more information about these security levels, see the InfoCenter at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
6. By default, all authenticated portal users will have editor access to the work page. In this
example, we set the editor security level to wpsContentAdministrators, so that it will no
longer be accessible to users outside out this group. To do this, first uncheck the Allow
inheritance check box next to Editor. This prevents the page from inheriting its security
settings from a parent entry, and allows us to specify our own security settings.
7. Click the pencil icon next to Editor.
8. Click the Add button.
9. Click the Search button to display all available user groups.
10.Select wpsContentAdministrators from the user group list.
Note: The wpadmins group has administrator access to all portlets and pages by
default.
11.Click the OK button.
36
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Users now have to be members of the wpsContentAdministrators or wpadmins group to be
able to see the work page. (Note that if you still have the work page hidden from the previous
steps, you will not be able to see the work page at all, even if you are logged in as an
administrator. We leave the work page disabled, as it is does not contain any useful portlets
for the ITSOCOOL scenario.)
Deleting a page
Another way to remove pages from the portal is to delete them from the navigation tree
altogether. Although we have no requirement to do this in the ITSOCOOL scenario, we
demonstrate how to do this in case you decide to delete some of your portal pages in the
future. To delete a page from the portal:
1. Log in to the portal as an administrator.
2. Open the administration page by clicking Administration.
3. Open the manage pages portlet by clicking Manage Pages under the Portal User
Interface heading.
4. Click Content Root in the manage pages portlet.
5. Click ITSOCOOL.
6. Click the bin icon in the row for the page entry you would like to delete.
7. Click OK when prompted to delete the page.
The page you selected to delete will now be permanently removed from the portal.
2.4.6 Introduction to Web content management in Portal Express
In WebSphere Portal Express there are a number of ways to manage Web content — that is,
to add, edit, and remove such things as text, images, and XML that are offered up to users
through your portal. Many of these functions can be performed from the portlet menus of
individual portlets, which can be accessed by clicking the down arrow located in each portlet
title bar.
Note: The portlet title bar is not always visible in some portlets. To view the portlet title bar,
you can move the cursor over the title bar of an individual portlet until the small down arrow
appears in the top right-hand corner of the portlet.
Overview of Web content management in Portal Express
WebSphere Portal Express also comes prepackaged with a number of tools to help you
manage Web content. The two main portlets that you will use to manage Web content are the
Web content management portlet and the Web content viewer portlet. The web content
management portlet gives you an aggregate view of all the Web content for your portal, and
can be used by administrators or managers to change Web content for other users. The Web
content management portlet also acts as a single interface to change content in multiple
areas of the site. The Web Content viewer portlet, on the other hand, can be used to create
new portlets based on content created in the Web content management portlet.
You can access both of these portlets from the Web Content page, which is accessible from
the Launch menu. To access the Web Content page, select Launch → Web Content.
Chapter 2. Introduction to customization in WebSphere Portal Express
37
Using Web content management provides the following functionality and benefits:
򐂰 Non-technical content owners can create and manage content, with a minimum of effort.
򐂰 Streamlines the Web content management process from content authoring, workflow,
management, integration, and delivery.
򐂰 Publishes information in minutes, for improved responsiveness to customers, partners,
suppliers, and employees.
򐂰 Personalized content can be delivered to each user.
򐂰 Web Content Management gives you a platform for high-value e-business applications.
򐂰 The solution is scalable from pilot to enterprise.
򐂰 Delivers faster implementation with a reusable component architecture.
򐂰 The application programming interface (API) externalization feature gives organizations
the ability to build solutions for migrating and importing from other Web content
management products, doing advanced rendering and batch processing of content.
򐂰 Total cost of ownership is reduced by enabling you to leverage existing infrastructures and
skills.
򐂰 Workflow and versioning functionality can help you through the document review and
approval process. Development features (which include templates to speed content
creation) allow you to create Web pages that aggregate content from various sources and
present it in a single, well organized format. These pages can be customized for viewing
on any device, including Web browsers, Pocket PC, Palm, or WAP/3G cell phones.
The Web Content Manager and Web Content Viewer are powerful and feature rich tools, and
are not extensively covered in this paper. Instead, we show a few of the most common uses
for these portlets in the context of the ITSOCOOL scenario. For more in-depth information
about Web content management, see the InfoCenter at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp
or the Web Content Management Redbook, IBM Workplace Web Content Management for
Portal 5.1 and IBM Workplace Web Content Management 2.5, SG24-6792,
http://www.redbooks.ibm.com/abstracts/sg246792.html?Open
In this section we cover how to:
򐂰 Edit site content (by editing a news item in the news portlet, and changing its text and
image, first through the news portlet itself, then through the Web Content Management
portlet).
򐂰 Add site content (by adding an announcement to the announcements portlet, then adding
an announcement containing text and an image).
򐂰 Remove site content (by deleting an announcement from the announcements portlet, first
through the announcement portlet itself, then through the Web Content Management
portlet).
򐂰 Create new content (by adding a new sales site area, creating a sales announcements
menu, and creating a new announcements portlet specifically for the sales department).
Over the course of this section, you will become familiar with some of the basic concepts
involved in Web content management in WebSphere Portal Express.
38
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Edit site content
An ordinary user (without access to the Web content management portlets) should complete
the following steps to change the text and image of a news item in the news portlet:
1. Move the cursor over the Reaching New Heights story in the news portlet, and click the
edit link that appears underneath the image of the building.
2. On the settings panel, change the Name field to CFCsAndTheEnvironment. The Name field
is used to uniquely identify each news story.
3. Change the Display Title to CFCs and the Environment. The display title is used as a
heading for your news story in the portal.
4. Change the Summary to Our company is making new headlines as one of the most
environmentally friendly companies in the country.
The summary field is used as a summary of your news story to appear on the portal.
5. Click Delete next to building.jpg to delete the image of the building.
6. In the Upload an image file section, click the Browse button. Select an image you would
like to use to replace the building image that was previously displayed in this news story.
You can use your own image or the same image we used. This image is available for
download. See Appendix C, “Additional material” on page 279, for information about how
to download this.
7. Specify CFCs and the Environment for the Alternate Text field. This field is used to display
information for the image tooltip and screen readers.
8. Copy the summary details into the Body field. The Body field contains the main body of
text for your news story.
9. Click the Save button.
The top news entry in your news portlet should reload and display as shown in Figure 2-23.
Figure 2-23 Adding the water drop image to this story
Content administrators can edit content using the Web content manager portlet. The Web
content manager portlet makes it easier to manage site content because it gives you a good
overview of all of the content in your site at a glance, and gives you more control over what
you do with this content.
Chapter 2. Introduction to customization in WebSphere Portal Express
39
To edit a news item from the Web content manager portlet, you must find the content list for
the news portlet. To do this:
1. Select Launch → Web Content.
2. Navigate to the Web Content Management page, as shown in Figure 2-24.
Figure 2-24 Web Content Management page
3. Navigate to the Content → By site area → Intranet → Home → News section (see
Figure 2-25).
Figure 2-25 Navigating within the WCM portlet
4. Scroll through the list to find CFCs and the Environment. Click the CFCs and the
Environment link (see Figure 2-26).
Figure 2-26 Navigating to content from within WCM Portlet
5. Click the Edit button to edit the news item.
6. Make a change to the news item and click Save → Save and close.
40
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
The news item will update with your changes.
Add site content
Users who are not content administrators can quickly add an announcement to the
Announcements portlet by using the add functionality available from the announcements
portlet. To do this:
1. Click the New Announcements link at the bottom of the announcements portlet.
2. Enter COL9000End in the Name field. This name uniquely identifies your announcement.
3. Enter No support for COL9000 for the display title. This field designates the title of your
announcement as it appears in the portal.
4. For the Description field, enter the following text:
The COL9000 product will no longer be supported. For support calls, customers
will need to go directly to the manufacturer.
Your settings should appear as shown in Figure 2-27.
Figure 2-27 Adding a new announcement to your announcements portlet
5. Click Save → Save and close.
Chapter 2. Introduction to customization in WebSphere Portal Express
41
This adds a new announcement to your announcements portlet (Figure 2-28), but this
announcement does not have any images associated with it. To add the capability to use
images in the announcement portlet, you need to use the Web content manager portlet.
Figure 2-28 Adding a new announcement to your announcements portlet
The first step is to make a backup of the default announcements menu, as you may make a
mistake at some stage and wish to revert back to the original announcements menu. You can
do this as follows:
1. Click Launch → Web Content.
2. Click the Web Content Management tab to open the Web content authoring portlet.
3. In the Web Content authoring portlet, expand Components and select Menu (see
Figure 2-29).
Figure 2-29 Web Content Authoring portlet, expand Components and select Menu
42
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Open the Announcements Menu entry in the component list (see Figure 2-30), and then
click Edit.
Note: You can locate the announcements menu by either using Search, entering a
page number in the Go to Page field, or paging through the Web content authoring
portlet.
Figure 2-30 Announcements menu entry in the component list
4. Click Save → Save as.
Important: Make sure to select Save → Save as, as selecting only Save overwrites the
template. We do not recommend modifying the items that are included out-of-the-box
without backing them up.
5. In the Save as window, type the new name and new display title for the Announcements
menu and click OK. For this example, use AnnouncementsMenuBackup for the name and
Announcements Menu Backup for the display title. You should see a confirmation that the
backup announcements menu was saved (see Figure 2-31).
Figure 2-31 Confirmation that the backup announcements menu was saved
Chapter 2. Introduction to customization in WebSphere Portal Express
43
Note: A component can become locked if you do not close it after editing, or if an
unexpected event occurs while you try to save it (for example, your browser might time
out because of a network issue, or you might not be using a required plug-in). You can
tell whether a component is locked because it will have a small padlock icon next to it
(see Figure 2-32). To unlock a component, check the box next to where the component
is listed in the components\menu list, and then select Unlock from the More Actions
menu.
Figure 2-32
6. Click the Close button to close the backed up Announcements menu, and then click OK
when prompted for confirmation.
Now that we have backed up the Announcements menu, we need a way for users to add an
image into an announcement. We can do this by editing the authoring template used by the
announcements portlet. When users add or edit announcements using the new authoring
template, they will be able to upload images to their announcements. Once we have set this
up, we then add an image tag to the HTML for the announcements portlet, so that these
images will be displayed to users.
Before proceeding, however, you should make a backup of the announcements authoring
template. This is so that if you make a mistake, you can revert back to a working version of
the template. To make the backup:
1. Select Authoring Templates from the Web content management portlet, as shown in
Figure 2-33.
Tip: You should download any plug-ins you are prompted for in order to get the most
out of the Web content management interface.
Figure 2-33 Select Authoring Templates from the Web Content Management portlet
44
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. Open the Announcement authoring template (Figure 2-34).
Figure 2-34 Open the announcement authoring template
3. Click Edit.
4. Click Save → Save as.
5. In the Save as window, type the new name and new display title for the new
Announcements authoring template. We used BackupAnnouncements for the name field
and Backup Announcements for the display title. Click OK when finished. You should see
a confirmation that your template was saved (Figure 2-35).
Figure 2-35 Confirmation that your template was saved
6. This creates a new authoring template called BackupAnnouncements, based on the
Announcement authoring template. Click the Close button to close the backup menu, and
then click OK when prompted for confirmation.
Chapter 2. Introduction to customization in WebSphere Portal Express
45
Now that we have created a backup of the announcements authoring template, the next step
is to edit the original authoring template to include an image.
1. Open the original announcements authoring template by selecting it from the authoring
templates category, as shown in Figure 2-36.
Figure 2-36 Open the original announcements authoring template
2. With the announcements authoring template open, click the Edit button at the top of the
form. Once the page reloads, click the Manage Elements button. (If this button does not
appear, the form is not in edit mode. Click the Edit button to change the form from read to
edit mode.)
The Element Manager panel should appear, as displayed in Figure 2-37. Currently, only a
rich text element is used for editing announcements with the announcement template.
Figure 2-37 Element Manager window
46
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
To add another element for graphics called image, modify this page so that it appears as
shown in Figure 2-38.
Figure 2-38 Adding another element for graphics
3. Click the Add button to add the image element to the authoring template.
4. Click OK to return to the ITSO Announcements template.
5. Click Save → Save and close at the top of the Web content management portlet. You
should see confirmation that the template was saved.
You have now updated the authoring template, which can be used to add entries with images
to the announcements portlet.
Chapter 2. Introduction to customization in WebSphere Portal Express
47
Tip: You can preview your authoring templates by using the Preview button on the
authoring template component while the form is being edited. Your previewed form should
contain an image section, as shown in Figure 2-39.
Figure 2-39 Previewed form should contain an image section
48
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Now we edit the announcements menu to change the way it displays each individual
announcement (in the form of an image that will be displayed for each announcement). To do
this:
1. Open the Announcements menu from the Components → menu list, as shown in
Figure 2-40.
Figure 2-40 Selecting the announcements menu
2. Click the Edit button to put the form into edit mode.
Chapter 2. Introduction to customization in WebSphere Portal Express
49
3. With the announcements menu component open, scroll down to the section of the form
that reads Design for each menu search result (see Figure 2-41). This section contains
HTML that defines how each entry in the announcements list appears.
Figure 2-41 Editing the HTML that controls the design of menu search results
4. Edit this field so that it contains the HTML shown in Example 2-1.
Example 2-1 HTML for menu search results
<tr>
<td width="100%">
<div class="expListItem" onmouseover="return expressListItemOver(this);"
onmouseout="return expressListItemOut(this);">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td nowrap><A class="expTitleLinkBold" HREF="<Placeholder tag="href"/>">
<IDCmpnt context="autoFill" type="content" field="title"/></A>
<br />
<Element context="autoFill" type="content" key="image"/>
<br>
<span class="expAuthor">
<IDCmpnt context="autoFill" type="content" field="authors"
separator=","/></span><br />
<span class="expDate">
<WorkflowCmpnt context="autoFill" type="content" field="publishdate" format="EEEE,
MMMM dd, yyyy"/></span>
50
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
</td>
<td style="white-space: nowrap;" align="right" valign="top"><div
style="visibility:hidden;"><AuthoringTool context="autoFill" name="Express Web
Content/InlineListItemTools"/></div></td>
</tr>
</table>
</div>
</td>
</tr>
This is the default HTML for announcement entries, only we have added an extra two
lines:
<Element context="autoFill" type="content" key="image"/>
<br>
The first line displays Web content called image, which is entered when the user adds an
announcement. By default, the default announcements authoring template does not give
users the option to upload images. The second line inserts a carriage return (a blank line).
5. Click Save → Save and close at the top of the Web content management portlet. You
should see a confirmation that the form was saved (Figure 2-42).
Figure 2-42 Confirmation for announcements menu
At this point, we have created a backup of our announcements menu and authoring template,
updated the announcements authoring template to allow users to add images, and updated
the original announcements menu to include an item called image for each announcement.
Next we apply the authoring template to all of the current content in the announcements
portlet. If you omit this step, then only new announcements use the new template — existing
announcements use the old template. To complete this step:
1. Open the announcement authoring template by clicking Announcement under the
Authoring Templates section on the Web content management portlet (Figure 2-43).
Figure 2-43 Open the announcement authoring template
2. Click the Apply Authoring Template button at the top of the form.
3. Select Add new elements and click OK. You should see a confirmation that the template
was applied.
Chapter 2. Introduction to customization in WebSphere Portal Express
51
Completing these steps applies the customized announcements authoring template to the
content in the announcements menu.
Now that we have set up the announcements portlet to use images, we add a new
announcement to test the new template. To do this:
1. Navigate back to the ITSOCOOL home page.
2. Click the New announcement link on the announcement portlet. You should notice that a
new entry for images has been added underneath the description field, as shown in
Figure 2-44.
Figure 2-44 New entry for images has been added underneath the description field
3. Enter in some appropriate details for your announcement. Notice that there is also a
section to edit the dimensions of your image (Figure 2-45). Change the dimensions to suit
the size of your image (we used 30x30).
Figure 2-45 Edit the dimensions of your image
52
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
4. When you are finished entering in your announcement, click Save → Save and close.
Make sure to upload an image to test your display layout. When you have saved your
announcement you should see output similar to that shown in Figure 2-46.
Graphic image added for announcement
Figure 2-46 Graphic image added for the announcement
Remove site content
To remove an announcement from the announcements portlet, ordinary users can complete
these steps:
1. Click the Delete link next to the entry you would like to delete in the announcements
portlet.
2. Click OK when prompted to delete the announcement.
Because announcements are each stored as content entries in the Web Content Manager, it
is also possible to remove announcements from the Web Content Management portlet. Using
the Web Content Management portlet gives you more control over how you manage your
Web content, as well as acting as a central place to add, edit, and remove content. Moreover,
it does not require you to sift through the portal trying to find the appropriate portlets to edit
when you need to remove individual content items.
To use the Web Content Management portlet to remove an announcement:
1. Click Launch → Web Content.
2. Click the Web Content Management tab to open the Web Content Authoring portlet.
Chapter 2. Introduction to customization in WebSphere Portal Express
53
3. In the Web Content Authoring portlet, expand Content → By Authoring Template →
Announcement, as shown in Figure 2-47.
Figure 2-47 Web content authoring portlet - navigating to the announcement
4. Check the entries you would like to delete. For this example, we check the box next to the
company picnic announcement.
5. Select Delete from the toolbar. Select OK when prompted to delete the item.
Create new content
In this section we discuss how to add new content to the ITSOCOOL site, in the form of a new
announcements portlet specifically designed for the sales department. This portlet uses
content in a new sales site area. Site areas are used in Web content management to
categorize content by a particular departmental or logical grouping.
Creating an ITSOCOOL site area
The first step is to create an ITSOCOOL site specifically for ITSOCOOL content. This step is
useful for categorizing your content more effectively, but is not strictly necessary.
To create the ITSOCOOL site, we make a copy of the intranet site and rename it to
ITSOCOOL. To do this:
1. Open the intranet site by checking the box next to the intranet link in the right-hand pane
of the Web content management portlet, which appears when you select the site areas\by
site category, as shown in Figure 2-48.
Figure 2-48 Site areas by site category
2. Click the Edit button.
54
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
3. Click Save → Save as.
4. Enter in ITSOCOOL for both the name and display title, as shown in Figure 2-49.
Figure 2-49 Saving the name of the site area
5. Click OK when finished. You should see confirmation that the new site area was saved
(Figure 2-50).
Figure 2-50 Confirmation that site area was saved
6. Click the Close button, and click OK when prompted to close the object.
You have now created an ITSOCOOL site based on the default intranet site, which you will
use to store all of the ITSOCOOL-related sales content. You can create a sales area
underneath the ITSOCOOL site as follows:
1. Click New → Site Area, as shown in Figure 2-51.
Figure 2-51 Creating the new site area
Chapter 2. Introduction to customization in WebSphere Portal Express
55
2. Select the ITSOCOOL site, as shown in Figure 2-52.
Figure 2-52 Select the ITSOCOOL site
3. Click OK.
4. Enter Sales for the name and display title, as shown in Figure 2-53.
Figure 2-53 Creating the name and display title
5. Click Save → Save and Close.
The ITSOCOOL sales area now shows up under ITSOCOOL, as shown in Figure 2-54.
Figure 2-54 ITSOCOOL sales area
56
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
The next step is to make a copy of the announcements menu to be used by the sales
department. This sales menu is then pointed at the ITSOCOOL sales site area, so it only
displays content created in this site area. To do this:
1. In the Web Content Authoring portlet, expand Components and select Menu
(Figure 2-55).
Figure 2-55 Expand Components and select Menu
2. Open the Announcements Menu entry in the component list (see Figure 2-56) and then
click Edit.
Note You can locate the announcements menu by either using Search, entering a page
number in the Go to Page field, or paging through the Web content authoring portlet.
Figure 2-56 Announcements menu entry in the component list
3. Click Save → Save as.
Important: Make sure to select Save → Save as, as selecting only Save will overwrite
the template. We do not recommend modifying the items that are included out of the
box without backing them up.
Chapter 2. Introduction to customization in WebSphere Portal Express
57
4. In the Save as window, type the new name and new display title for the announcements
menu and click OK. For this example, use SalesAnnouncementsMenu for the name and
Sales Announcements Menu for the display title. You should see a confirmation that the
sales announcements menu was saved (see Figure 2-57).
Figure 2-57 Confirmation
5. Scroll down to the Site Areas section and uncheck the boxes for Include ancestors and
Include descendents (Figure 2-58), as this improves performance.
6. Now we will tell the sales menu to only display content from the ITSOCOOL sales site
area. Click the Select Site Areas button in the Site Areas section of the form.
Figure 2-58 Select Site Areas button in the Site Areas section of the form
7. Select the sales site area from the list (Figure 2-59) and click OK.
Figure 2-59 Select the sales site area from the list
58
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
8. The ITSOCOOL sales site now shows in the list of selected areas (Figure 2-60). Click OK
to continue.
Figure 2-60 ITSOCOOL sales site now shows in the list of selected areas
9. Click the Save and close button to close the sales announcements menu.
Now that you have created an ITSOCOOL sales site area and a sales menu, you need to
create the content for the list. The content is created in the new ITSOCOOL sales site area.
To create a sample announcement in the sales announcements list:
1. Click New → Content (Figure 2-61).
Figure 2-61 Click New → Content
2. Select the Announcement authoring template, as shown in Figure 2-62.
Figure 2-62 Select the announcement authoring template
3. Click the OK button.
Chapter 2. Introduction to customization in WebSphere Portal Express
59
4. Enter in some details for your announcement. We used FridgeKing and Breezeway for the
name, FridgeKing and Breezeway to merge for the display title, and FridgeKing and
Breezeway to merge for the description. Click Save → Save and close when you are
finished.
5. On the next window, expand the ITSOCOOL site and select the sales site area, as shown
in Figure 2-63.
Figure 2-63 Select the sales site area
6. Click OK. You should see a confirmation message that the content was created
successfully (Figure 2-64).
Figure 2-64 Confirmation
Now that you have created some content for the sales announcements list, the next step is to
create the new sales announcements portlet itself. We then configure the sales portlet to use
the ITSOCOOL sales content.
Complete these steps:
1. Navigate to the ITSOCOOL Welcome page.
2. Click the Portlets link in the top right of the portal window to open the portlet palette.
3. In the portlet palette search box, type web content and click the search button. A list of
portlets that match the web content search criteria is displayed, as shown in Figure 2-65.
Figure 2-65 Portlet Palette search box
60
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
4. Click and drag the Web Content Viewer portlet onto the portal underneath the my weather
portlet. You may need to drag the Web content viewer portlet to another place on the
window if your resolution is too low to display the far right column of the portal.
5. Click Portlets to hide the portlet palette.
6. Move the cursor over the top right-hand corner of the Web content viewer portlet and click
the arrow that appears there to open up the portlet menu. Click Edit Shared Settings.
7. Change the content type to Component (see Figure 2-66), and click the Edit button next
to the component section heading.
Figure 2-66 Web Content Viewer
8. Select Express Web Content from the Library drop-down.
9. Select Menu from the components list, then scroll through the list to find the sales
announcements menu. Check the circle next to the Sales announcements menu, as
shown in Figure 2-67.
Figure 2-67 Check the circle next to the Sales announcements menu
10.Click the OK button to return to the Web Content Viewer configuration page.
11.Click the Edit button next to the content section heading.
Chapter 2. Introduction to customization in WebSphere Portal Express
61
Why do I need to perform this step?
The reason this is required is to give the selected component a context for when the
portlet is first rendered. The InfoCenter describes this through the use of an example
that may helps to explain:
If a content item called news is selected as the context for a navigator, when the
portal page is first opened, the navigator will behave as though news is the current
content item. You are required to select a content item even for components that do
not require context, such as HTML components.
So in this case, the component being a navigator, needs to have a current context
since the navigator will use this in determining how or what to display. I would
imagine that for consistency, this is required even for components that do not strictly
require a current context.
12.Select Express Web Content from the Library drop-down.
13.Select Sales from the ITSOCOOL site area, as shown in Figure 2-68.
Figure 2-68 Select Sales from the ITSOCOOL site area
14.Click OK to return to the Web Content Viewer configuration page.
15.Type in Sales Announcements for the Portlet Display Title field at the bottom of the Web
Content Viewer portlet.
16.Click OK on the Web Content Viewer configuration page to save your changes.
You have now finished setting up your sales announcements portlet, which should appear as
shown in Figure 2-69.
Figure 2-69 Completed sales announcements portlet
In Chapter 7, “Introduction to composite application framework and templates” on page 233,
we discuss how to add this sales announcements portlet to a composite application template
for the sales department at ITSOCOOL.
62
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2.5 Customizing the look and feel
In the following section we describe the process for changing the look of the Portal from the
standard out-of-the-box appearance to the customized ITSO Cool appearance shown in the
sample application.
2.5.1 Themes and skins
Themes and skins form two of the fundamental building blocks of customization in
WebSphere Portal Express.
A theme is the over arching design for your portal site, and controls the navigation,
appearance, and layout of the portlet container. Many of the colors, fonts, and images for
your portal are controlled by theme settings. Themes are a combination of image files, JSP™
files, and style sheets.
A skin represents the border rendering around individual components, such as row
containers, column containers, or portlets (but not the portlet title bars). Skins consist of JSP
files, image files, and style sheets.
WebSphere Portal Express allows you to use multiple themes and skins on your system. The
basic installation of Portal Express comes with several predefined themes and skins.
Your portal always has one theme and one skin selected as default. Except where otherwise
explicitly specified, the whole portal is rendered using the default theme and skin.
2.5.2 Using the built-in themes
Since you probably want to customize your portal according to your own corporate look and
feel, the predefined set of themes and skins only serves as a guide for understanding how
these tools work. In this section we use an ITSOCOOL theme, which is based on one of the
default themes that comes with WebSphere Portal Express. You can download the
ITSOCOOL theme from the IBM Redbooks publication download site associated from this
paper. See Appendix C, “Additional material” on page 279, for information about how to
download this material. The ITSOCOOL theme can be used to bring your portal in line with
the ITSOCOOL corporate look and feel, and as a guide for future theme development.
Themes have the most impact on the graphic design of your portal. Themes contain
information about the fonts and colors used on your portal, and also contain the majority of
the background images used on the portal.
Chapter 2. Introduction to customization in WebSphere Portal Express
63
Figure 2-70 shows the two basic themes that are a part of each WebSphere Portal Express
installation. You can see the differences between these two themes below.
Figure 2-70 Themes IBM (left) and Express (right)
Setting the default theme for the portal
WebSphere Portal Express comes with the Express theme set as the default. As an
alternative, if you want to try setting your portal to use the IBM theme by default, follow these
steps:
1. Log in as administrator.
2. Switch to Administration by clicking Launch → Administration.
3. From the navigation pane select Portal User Interface → Themes and skins.
4. Select the IBM theme and click Set as default portal theme.
5. Once the default theme has been changed, click Launch → Home to return to the portal
page and see the change.
Figure 2-71 Switching between themes and skins - default theme for the portal
Setting the theme for individual pages
Since themes are very flexible in IBM WebSphere Portal Express, you can use a different
skin for each individual portal page if required. There are some scenarios where you would
want to use different themes for different groups of pages, such as when you want to visually
differentiate between different parts of your intranet.
64
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Note: Most of the predefined pages in the portal tree are preconfigured to use specific
themes. This means that these pages ignore the default portal theme unless you explicitly
change the theme preference in each page. That is why it is important to understand how
to set up the theme for individual pages, even if you do not want to use this option.
To configure the default theme for a single page:
1. Log in as administrator.
2. Switch to Administration by clicking Launch → Administration.
3. From the left navigation, choose Portal User Interface → Manage pages.
4. Go to any page you want to change (for example, to change the default theme of the Work
page, go to Content root → Intranet JumpStart → Work) and click the Edit page
properties icon.
5. On the next page, select the specific theme you want and click OK.
Figure 2-72 Specifying the default theme for individual pages
Note: What is the difference between inherit parent theme and portal default theme?
Inherit parent theme means that whenever the page is opened, the portal will use the
theme preference set in the page that contains the current page.
If you go to Administration → Manage Pages you can see that the content root is the
container object for all other items in the portal (but its properties are not editable). The
intranet JumpStart is the parent page for home, work, and collaboration by default.
Objects that are directly contained by the content root cannot inherit their theme from any
parent. In this case, you use portal default theme instead. This setting means that the page
uses the theme that is set as the default theme for the entire portal.
Chapter 2. Introduction to customization in WebSphere Portal Express
65
2.5.3 Using the built-in skins
As discussed at the beginning of the previous section, skins impact the way individual portlets
and their frames are rendered by the server. In this section we go into more detail about how
you can use skins effectively.
Skins are independent from themes in that you can install and edit themes and skins
independently. On the other hand, skins are related to themes in that an administrator can
decide if you want certain themes to use certain skins (instead of the portal’s default). For
example, the IBM and Express themes are configured to use the IBM skin instead of the
portal’s default. We discuss this feature later in this chapter.
WebSphere Portal Express comes with the following predefined skins by default:
򐂰
򐂰
򐂰
򐂰
IBM
ThinSkin
NoSkin
IFrame
IBM, ThinSkin, and NoSkin are quite similar to each other. The difference between these
skins is the way in which the portal renders the titlebar and the surrounding boxes of each
portlet. The skin you end up choosing for your corporate site is largely a matter of personal
preference. The IBM skin uses traditional rectangular boxes around each portlet. On the other
hand, ThinSkin and NoSkin are useful if your portlets already contain some kind of visible
boundaries, and you do not want the portal to render another one around each portlet.
The IFrame skin is fairly different from the other skins, and uses special HTML elements
called inline frames (IFRAMEs) to render the contents of each portlet. IFRAMEs are used in
all of the recent browsers, and are treated as separate browser windows (that is, an IFRAME
is a frame within a frame).
As a result, if certain portlets are slow to load and cause the rest of the portal to load slowly,
you can consider using the IFrame skin for that portal page. In this case, all portlets on the
page will load independently, and you can start using some of the portlets while the others
are still loading.
Note: You cannot set the IFrame skin as the default skin for your portal.
An interesting side effect of the IFrame skin is that portlets rendered with the IFrame skin all
have the same width and height, defined internally in the configuration for the IFrame skin.
The width is set to 100% (which means that the portlet resizes to fit the table cell it is
contained in) and the height to 250 pixels by default. If you want to change these dimensions,
you can do so by editing the Control.jsp file in the skins/html/IFrame directory, which is
located in the themes and skins root directory. Once you have opened this file, locate the
markup for the IFRAME as follows, and set the width and height attributes as desired:
<iframe src=”” SCROLLING=”auto” FRAMEBORDER=”0” width=”100%” height=”250”>
66
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
The themes and skins root directory is located in:
򐂰 Windows:
was_profile_root\installedApps\cellname\wps.ear\wps.war
򐂰 Linux®:
was_profile_root/installedApps/cellname/wps.ear/wps.war
򐂰 i5/OS®:
app_server_root/installedApps/cellname/wps.ear/wps.war
Setting the default skin for the portal
The default skin does not play as large a role in the look and feel of your portal as the default
theme, and is used for more subtle design modifications to the portlets themselves. Most of
the themes (including the out-of-the-box themes) that are built in the portal are tied to one
specific skin. This means that whenever one of these themes is selected, the default skin for
the portal is ignored (in favor of the skin specified in the theme).
If you are interested in how to set the skin for individual themes, or how to verify whether a
theme has a certain skin tied to itself, see “Setting the skin for individual themes” on page 67.
If you are interested in setting the default skin for your portal (which will apply for those
themes that do not have a skin specified), then follow these steps:
1.
2.
3.
4.
Log in as administrator.
Switch to administration by clicking Launch → Administration.
From the navigation pane select Portal User Interface → Themes and skins.
Select one of the skins and click Set as default portal skin.
Figure 2-73 Changing the default skin of the portal
Setting the skin for individual themes
Both out-of-the-box themes (IBM and Express) come with preconfigured preferences to use
particular skins and ignore the portal’s default skin. In this section, we show you how to
change this preference:
1. Log in as administrator.
2. Switch to administration by clicking Launch → Administration.
3. From the navigation pane select Portal User Interface → Themes and skins.
4. Select one of the themes (for example, IBM) and click Edit theme.
5. If you look below the All skins list box, you can see that the default skin for this theme is
IBM. This is what we are going to change.
Chapter 2. Introduction to customization in WebSphere Portal Express
67
6. From the Skins for this theme list box, pick one of the skins (other than IBM) and click Set
as default.
7. Do not forget to click OK. Otherwise, your change is not applied to the portlets.
8. Select one of the skins and click Set as default portal skin.
9. Click Launch → Home to return to the portal page and see the difference.
Figure 2-74 Changing the default skin of a theme
If you want to configure a theme to use the portal’s default skin rather then a specific skin, you
can do it in the following way:
1. Log in as administrator.
2. Switch to administration by clicking Launch → Administration.
3. From the navigation pane select Portal User Interface → Themes and skins.
4. Select one of the themes (for example, IBM) and click Edit theme.
5. Click all items in the Skins for this theme list box one by one and remove them by clicking
the left arrow next to the list box.
6. When the last skin is removed from the list box and you look below the All skins list box,
you can see that the default skin for this theme using portal wide setting IBM.
7. Do not forget to click OK. Otherwise, your change is not applied to the portlets. Now
whenever you change the portal wide default skin, all portlets respect it if they are
rendered using this theme.
Figure 2-75 Setting a theme to user the portal-wide default skin
68
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2.5.4 Creating your own theme
At this point you might be interested in giving the portal a new look and feel, instead of using
one of the predefined designs. To do this you need to create your own theme. You can use
one of the default themes as a starting point, or download the ITSOCOOL theme from the
IBM Redbooks download site associated with this paper. See Appendix C, “Additional
material” on page 279, for information about how to download this material. In this section we
step through the process of how the ITSOCOOL theme is created.
Although themes in WebSphere Portal Express are not difficult to understand, they have to
respect a certain file structure. This is why we recommend creating your own theme by
creating a copy of one of the existing themes, and then changing the copy. In this section we
create a custom theme for the ITSOCOOL portal.
Creating a copy of an existing theme consists of two steps: copying the theme’s files to a new
directory on the server’s file system, and letting the server know about this new directory.
In this chapter, we create a copy of the default Express theme, and then we show you how to
customize this theme. To create your own copy of the Express theme:
1. Copy the theme’s files to a new directory:
a. Go into the root directory of all themes on the server:
•
Windows:
was_profile_root\installedApps\cellname\wps.ear\ wps.war\themes\html
•
Linux:
was_profile_root/installedApps/cellname/wps.ear/wps.war/ themes/html
•
i5/OS:
app_server_root/installedApps/cellname/wps.ear/wps.war /themes/html
b. Create an exact copy of the Express directory with all files and subdirectories in it and
give it a new, unique name (such as Express - ITSO).
Figure 2-76 Creating the files for your own theme
2. Add the new directory to the server’s configuration:
a. Log in as administrator.
b. Switch to administration by clicking Launch → Administration.
Chapter 2. Introduction to customization in WebSphere Portal Express
69
c. From the navigation pane select Portal User Interface → Themes and skins.
d. On the right side, click Add theme.
e. Fill in the dialog box, giving a name to the new theme and entering the correct directory
name corresponding to the directory you have created for the theme (for example,
Express_ITSO). You can give the theme any name you want to — it does not need to
be the same as the name of the directory (such as what we have done in the example).
Figure 2-77 Adding the new theme to the configuration
f. Click OK. Now the new theme is ready to use.
3. Setting the new theme as the default for the portal:
a. Select the newly created theme from the list (Express_ITSO).
b. Click Set as portal default theme.
Customizing your own theme
Once you have created your own theme based on one of the out-of-the-box themes, you are
ready to create your own look and feel for the portal. In this section we cover:
򐂰 How themes work
򐂰 Changing the banner and the logo
򐂰 Customizing colors
How themes work
Themes consist of images, Java Server Pages (JSPs), and style sheets. Images form the
graphical part of the portal, and the JSPs and style sheets are responsible for rendering the
underlying content (HTML, menubars, portlets).
When a portal page is hit, the system calls the Default.jsp, which starts the rendering of the
portal. There is one exception: if a portlet is shown in a standalone window or if it is rendered
using the IFrame skin inside of an inline frame, then the system uses Plain.jsp instead.
Cascading Style Sheets (CSSs) are also generated by JSPs. A common practice is that
instead of letting the Web designers edit the CSS files directly, they just modify the
colors/default.properties file, which is used by JSPs use to generate CSS files.
70
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Note: For more details on what each individual JSP in the theme directory is used for, visit
the Portal 6 Express InfoCenter at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.ent.doc
/wps/dgn_themes.html
Where theme files are stored
The theme files are located in the following directories:
򐂰 Windows:
was_profile_root\installedApps\cellname\wps.ear\wps.war\themes\html\<your_theme>
򐂰 Linux:
was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/html/<your_theme>
򐂰 i5/OS:
app_server_root/installedApps/cellname/wps.ear/wps.war/themes/html/<your_theme>
Who should modify which files
Web designers are encouraged to modify images and static HTML code in JSP files, and the
default.properties file in the colors directory.
Advanced developers can make changes to the dynamic parts of JSP files.
Viewing changes without restarting - automatic JSP reloading
WebSphere Portal Express (especially if runs in a production environment) does a lot of
caching to improve performance. This means that certain dynamic content (such as JSP
pages) are compiled only once, and then they run from the cache. This makes portal pages
load significantly faster.
However, as a side effect it is difficult to test changes to JSP files, and can involve restarting
the portal server. To avoid this, WebSphere Portal Express has a special switch that tells the
server to recompile JSP pages when they are accessed.
To enable automatic JSP reloading:
1. Open the file was_profile_root/config/cells/cellname/applications/
wps.ear/deployments/wps/wps.war/WEB-INF/ibm-web-ext.xmi.
2. Find the entry shown in Example 2-2 in this file.
Example 2-2 Entry
<webappext:WebAppExtension xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"
xmlns:webappext="webappext.xmi" xmlns:webapplication="webapplication.xmi"
xmi:id="IBM_WPS_Ext" reloadInterval="3" reloadingEnabled="false"
fileServingEnabled="true" directoryBrowsingEnabled="false"
serveServletsByClassnameEnabled="false" preCompileJSPs="false">
3. Change the value for reloadingEnabled to true.
4. Save the changes.
5. Restart the portal server.
Chapter 2. Introduction to customization in WebSphere Portal Express
71
Important: It may take a few minutes after you first restart the portal server for JSP
reloading to take effect.
In order to use automatic JSP reloading properly, whenever you modify any JSP in the
portal server, you need to open and re-save the root JSP file (usually the Default.jsp file) in
the /themes directory. This notifies the server that a JSP file has been changed.
If you are working in IFrame mode, open and re-save the Plain.jsp file as well.
If your JSP files are still not reloading, it is most likely because of the cache in your
browser. Read how to empty your cache below.
Emptying the cache of your browser is important
WebSphere Portal Express instructs your Web browser to cache some files (including CSS)
that are not likely to change often. This improves performance and decreases load on the
server. However, a side effect of this is that it might take a long time for your browser to
reload certain files from the server, even if they are recompiled and ready thanks to automatic
JSP reloading.
In this case, you need to empty your browser’s cache if you feel that you do not see the most
recent versions of the JSP files you modified.
If you are using Microsoft Internet Explorer®, you can empty your cache in the following way:
1. Click Tools → Internet options (Figure 2-78).
2. Click Delete Files and confirm with OK.
3. Possibly close and reopen your browser.
If you are using Mozilla Firefox, you can empty your cache in the following way:
1.
2.
3.
4.
Click Tools → Options.
Go to Privacy → Cache tab (Figure 2-78).
Click Clear cache now.
Possibly close and reopen your browser.
Figure 2-78 Emptying cache in Microsoft Internet Explorer and Mozilla Firefox
72
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Changing the logo
This section describes how to change the logo in the ITSOCOOL portal. To change the logo
(in themes based on the portal’s Express theme):
1. Set the theme as the default theme for your portal (we are using ITSOCOOL in the
example).
2. Go into the directory where the ITSOCOOL theme files are stored. If you do not know
which one it is, refer to “Where theme files are stored” on page 71.
3. Go into the colors/default directory.
4. Replace the toolbar_logo.gif image with your own image.
5. Click Reload/Refresh in your browser.
If you were successful, you should see the new logo in the portal (Figure 2-79).
Figure 2-79 Changing the logo
Tip: If you still see the old logo in the portal after changing the logo, it could be because:
򐂰 You need to refresh your browser’s cache as described in “Emptying the cache of your
browser is important” on page 72.
򐂰 The page you are viewing (for example, home) is configured to use a different theme.
Click the small arrow in the title of the page and choose Edit Page Layout to verify.
򐂰 The page you are viewing (for example, home) is configured to inherit the default theme
of its parent and that is different from the default theme. Go to Administration →
Themes and skins and locate the page’s parent page to verify.
Changing the portal banner
In a very similar way to how we changed the logo, we are now going to change the underlying
portal banner.
Changing the portal banner (in themes based on the portal’s Express theme):
1. Go into the directory where your theme files are stored. If you do not know which one it is,
refer to “Where theme files are stored” on page 71.
2. Go into the colors/default directory.
3. Replace the toolbar_background.gif image with your own image.
4. Click Reload/Refresh button in your browser.
Chapter 2. Introduction to customization in WebSphere Portal Express
73
If you were successful, your banner should be changed (Figure 2-80).
Figure 2-80 Changing the banner
74
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Changing colors using style sheets
Now that you have started to customize the look of your portal, you might want to change
some colors on the page. This section describes how to change the color of the following
artifacts:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Links in the quick navigation (1)
Palette links (2)
Active page title (3)
Launch menu active background (4)
Footer links (5)
Top navigation background (6)
Button background (7)
Figure 2-81 Changing colors
Color codes, which identify all colors used on the portal page, are stored in Cascading Style
Sheet files. CSS files are generated automatically by styles.jsp, which is located in your
themes folder. The styles.jsp reads the default.properties (a file of attributes) to obtain
information based on which it generates the CSS file used by the portal.
Chapter 2. Introduction to customization in WebSphere Portal Express
75
Tip: We recommend that any property in the styles.jsp file (or any JSP that references an
attribute from the default.properties file) be changed in the default.properties file.
In the case where you need to change a style or an attribute that is not contained by the
default.properties, we recommend that you modify the styles.jsp or other referenced JSPs.
Before you start, go into the directory where your theme files are stored. If you do not know
which one it is, refer to “Where theme files are stored” on page 71. Go into the colors
directory and open the default.properties file in Notepad.
1. To change the colors of the quick navigation, locate the line shown in Example 2-3 in the
properties file and change the color code value beginning with the number character (#) to
your own code.
Example 2-3 Change colors in the quick navigation
breadcrumbText=#0063dc
globalActionText=#0063dc
2. To change the colors of the palette links, locate the line in Example 2-4 in the properties
file and change the color code as described above.
Example 2-4 Change colors of the palette links
footerText=#0063dc
3. To change the color of the active page title, search for the lines shown in Example 2-5 in
the properties file.
Example 2-5 Change color of the active page title
topNavFirstRowSelectedText=#0063DC
4. To change the background color of the selected item in the launch menu, find the line in
Example 2-6 in the properties file and change its value.
Example 2-6 Change colors in the launch menu
launchMenuSelectedBackground=#0063DC
5. To change the color of the links, find the line in Example 2-7 in the properties file and
change its value.
Example 2-7 Changing colors of links in the footer
footerText=#D93749
6. In order to change the background color of the top navigation bar, you will have to replace
the topnav_background.gif image in the default directory.
7. In order to change the default background color of buttons, you need to change the
ButtonBackground.gif file in the default directory.
8. To change the color used to fill the portlet title bars, change the portletTitleBarBg.gif file in
the default directory.
76
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2.5.5 More about CSS style sheets
As discussed earlier, the CSS style sheets that are used for the portal page are dynamically
generated by JSPs located in the /themes/IBM/ directory. Dynamically generated style sheets
require far fewer files to support variations based on locale, browser, and color palette than
static style sheets. It is possible to change the tag definitions and the class definitions in the
CSS style sheets. However, make sure that you do not delete any style sheets or remove any
style classes, as portlets require these style classes for JSP output.
The following list provides information about the CSS file structure:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
styles.jsp - root page that includes children
styles_cacheSettings.jspf - sets headers to control how the output CSS is cached
styles_rules.jspf - defines logic to be consumed by style definitions
styles_theme.jspf - contains style definitions for the theme
styles_portlets.jspf - contains standard styles for portlets
styles_ibm.jspf - contains styles for IBM portlets
styles_help.jspf - contains styles for portlet help files
styles_oob.jspf - contains styles for out-of-box Information portlet JSPs
Modifying dynamic styles
All of the logic controlling the generation of dynamic styles is contained in styles_rules.jspf.
This JSP fragment creates a map of rules for use by the style definitions. Refer to this file for
the rules available for use in your style definitions.
If you want to add your own additional styles, create your own JSP fragment (such as
styles_myStyles.jspf) and modify styles.jsp to include the fragment. In this way, your styles
are incorporated into the portal style sheet, and are able to use the dynamic rules.
Caching dynamic styles
The output of dynamic styles varies by browser, locale, and color palette. The
<portal-theme:cacheProxyUrl> tag generates a cacheable URL to styles.jsp that encodes the
browser, locale, and color palette variables. This allows the output CSS to be cached by the
server for improved performance.
Style classes for portlets
The style sheets that are used by IBM WebSphere Portal Express contain classes that can be
used by portlets to ensure visual consistency among portlets on the page. Using these
classes ensures that no matter what theme has been selected, the portlet look and feel
matches that of other portlets and the rest of the portal page.
To determine which classes to invoke in your portlet output, portlet developers can examine
the styles_portlets.jspf file that is located in the IBM WebSphere Application Server directory:
򐂰 Windows
was_profile_root\installedApps\cellname\wps.ear\wps.war\themes\html\IBM\
򐂰 Linux
was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/html/IBM/
򐂰 i5/OS
app_server_root/installedApps/cellname/wps.ear/wps.war/themes/html/IBM/css
The file includes comments explaining the use of each class. Portlet help uses the style
classes in styles_help.jspf. For most tags, using class="help" ensures that the portlet help
renders consistently with help for other portlets on the page.
Chapter 2. Introduction to customization in WebSphere Portal Express
77
2.5.6 Changing the portal page help
WebSphere Portal Express provides help information for the portal site when users click the
help link that is provided in the toolbar. You should customize this help page to reflect the
content and information for your organization's site. Help topics should address the needs of
the portal users, and not provide access to information about administering the portal. The
help page that is provided by WebSphere Portal Express provides definitions for common
portal terms, such as portlet and skin. You should either keep these definitions for your portal
users or provide your own.
Location of the help
The portal help link must be located in a theme JSP, so that it can always be accessible from
any page in the portal. After installation, WebSphere Portal Express provides the help link in
banner_toolbar.jspf in the /themes/html/IBM directory. The markup for the help link is
identified by the following comment:
<%-- help --%>
For customized themes, this help link could be placed in other theme JSP files. To provide
site-specific help, you can edit the target of the help link or edit the help source that is
provided by WebSphere Portal Express.
To change the help link, edit the link in the JSPs that are provided for each theme that you
use. The following example shows the default help link target:
href="<%= wpsDocURL %>/help/index.html"
To edit the help source, edit the portal help file at the following location:
򐂰 Windows and Linux
was_profile_root/installedApps/cellname/wps.ear/wps.war/doc/locale/help/index.html
򐂰 i5/OS
app_server_root/installedApps/cellname/wps.ear/wps.war/doc/locale/help/index.html
Changing the portal help window size
By default, the help link sets the portal help window width to 800 pixels and the height to 600
pixels, using the JavaScript onClick event handler of the anchor tag. To change the window
size:
1. Locate the markup for the help link.
2. In the corresponding anchor tag, look for the width=800,height=600 values in the
window.open() method.
3. Change these values to the desired width and height values for the help window.
78
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2.5.7 Removing sign-up links from the portal
By default, WebSphere Portal Express provides sign-up links as part of the Login window
(shown in Figure 2-82), which allows new users to sign up and log in to the site without a user
name and password. This is useful when a portal site is customer facing, or it is impractical for
an administrator to be adding in new login details for each new user. You can still restrict what
newly signed up users see in the portal, and it is likely that you will want to restrict access to
parts of your site unless users have a valid user name and password. Given that the
ITSOCOOL portal is an employee intranet, it makes sense to restrict access to the portal for
unauthenticated users. In this case it is preferable to hide the sign-up links from the Login
portlet, which forces new users to obtain a valid account before logging in to the portal.
Figure 2-82 Login page with the sign-up link
To remove the Sign-up link from the Login portlet:
1. Log in to WebSphere Portal Express as an administrator.
2. Click Administration.
3. Navigate to Portlet Management → Portlets.
4. Type Login into the search box and click Search. The portal should find and display an
entry for the login portlet.
5. Click the Configure icon next to the login portlet to open the configuration page for the
login portlet.
6. Make sure that the ShowSignupLink parameter is set to false. You can change the value
of this parameter by clicking the Edit button next to the ShowSignupLink field, and then
typing false in the value box that appears.
7. Save your changes.
Chapter 2. Introduction to customization in WebSphere Portal Express
79
After this operation, both Sign up and Sign up now links should be removed from the home
page.
Figure 2-83 Login page without the Sign up link
2.5.8 Configuring the mail and calendar portlets
WebSphere Portal Express comes with mail and calendar portlets (called PIM portlets, or
Personal Information Management portlets) that allow users to link in to a number of backend
mail and calendar systems, such as Lotus Domino and Microsoft Exchange. These portlets
are included by default on the Collaboration page of the default intranet site included with
WebSphere Portal Express, but need to be configured in order to connect to a server that
provides mail and calendar functionality.
80
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
You can see the mail and calendar portlets configured correctly in Figure 2-84.
Configured Mail Portlet
Configured Calendar Portlet
Figure 2-84 Example of a properly configured mail and calendar portlet
Alternatively, when the mail and calendar portlets are not yet configured, and you click the
Collaboration tab, you will see a notification that configuration information is still missing,
similar to that shown in Figure 2-85.
Figure 2-85 Example of missing configuration information for the mail and calendar portlets
Chapter 2. Introduction to customization in WebSphere Portal Express
81
Setting up mail and calendar portlets for Lotus Domino
To configure your mail and calendar portlets to work with Lotus Domino, you have three
options:
򐂰 Using the Domino Integration Wizard
This is the best option provided that you are using WebSphere Portal Express 6.0.1 or
later (this wizard is not provided in previous versions of WebSphere Portal Express). The
Domino integration wizard configures your PIM portlets to use a Lotus Domino directory
for mail and calendar, configure your portal to access a Lotus Sametime server, and also
enables single sign on (SSO) for your environment. SSO gives users access to multiple
resources while only requiring the user to authenticate once (when logging in to the
portal). If you are going to be using SSO with Domino, it makes sense to set up
WebSphere Portal Express to use a Lotus Domino server for authentication via LDAP, so
that users can log in to the portal using their Domino user names and internet passwords.
The configuration of this is handled in the LDAP configuration wizard, which you can run
anytime after installing WebSphere Portal Express.
Important: For information about using the Domino-WebSphere Portal Integration
wizard overview, refer to the Portal 6.0.1 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/inst_updates.html
From within the InfoCenter, search for the text Domino-WebSphere Portal Integration
wizard overview.
Additionally, refer to Appendix A, “Installation and configuration best practices” on
page 265, for high-level help about how to install and configure Portal Express.
򐂰 Configuring Lotus Collaborative Components manually
This option gives you more fine-grained control over the Domino integration process, but it
is more difficult than the wizard, as it requires more knowledge on the part of the
administrator. Configuring the Lotus collaborative components manually is not covered in
this paper. For more information about this topic, see the InfoCenter links below.
򐂰 Configuring the mail and calendar portlets manually in the portal server
This way consists of setting up the mail and calendar portlets using the Edit Shared
Settings and Configure buttons of the portlets. We do not recommend this option if one of
the above two alternatives (Domino Integration Wizard or configuring Lotus Collaborative
Components) is available.
Important: If you are going to use a Domino server for LDAP authentication in WebSphere
Portal Express, you need to run the LDAP configuration wizard before you run the Domino
integration wizard.
Note: For a detailed description of running the Domino Integration Wizard, read
Appendix A, “Installation and configuration best practices” on page 265.
82
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Note: InfoCenter links:
򐂰 Overview and prerequisites for the Domino Integration Wizard
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.exp.doc
/collab/i_domi_c_wizard_messaging.html
򐂰 Running the Domino Integration Wizard
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.exp.doc
/collab/i_domi_t_wizard_messaging.html
򐂰 Integrating Lotus Collaborative Components (manually)
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.exp.doc
/collab/ksa_cfg_main.html
2.6 Conclusion
In this chapter we discussed how to perform some basic customizations in WebSphere Portal
Express. We demonstrated some of the basic ways to manage Web content in the context of
the ITSOCOOL scenario, and showed how to manipulate portal themes and skins to tailor the
design of the portal to be more in line with the ITSOCOOL corporate identity.
If you have followed through the steps in this chapter, you should have an ITSOCOOL portal
site in WebSphere Portal Express. The site will have a design in line with the ITSOCOOL
corporate look and feel, and contain ITSOCOOL-specific content.
In the next chapter, we focus on introducing Lotus Component Designer, one of the tools
provided with Portal Express Version 6.0, to modify and build components.
Chapter 2. Introduction to customization in WebSphere Portal Express
83
84
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
3
Chapter 3.
Introduction to Lotus
Component Designer
Lotus Component Designer is a development tool that helps developers quickly create new
applications that provide rich user interfaces and supporting business logic without writing
code. These applications form the constituent components of the work environment delivered
by IBM WebSphere Portal Express V6. Lotus Component Designer comes at no extra charge
and is provided directly with IBM Portal Express. In this chapter we give you an introduction to
the technologies used within Lotus Component Designer (LCD) and show you how to perform
basic customization on sample components provided with the product.
We begin by guiding you through the installation, then introducing the basic design elements
and concepts. Building upon this introduction, we show how to install and perform basic
customizations on the sample applications that are provided with LCD. This exercise serves
to reinforce how easy it is to change the look and feel of sample LCD components to align
with your corporate image. The specific example in this chapter is based on customizing the
contact list sample application to change the look and feel to meet the corporate standards of
our fictitious ITSO Cool company.
Once the component is complete, we then show how to deploy it to a Portal server, and how
to place the component on the portal page. Finally, we customize the parameters and test the
application for contact information.
Note: This chapter serves as an introduction to Lotus Component Designer and focuses
on performing basic customizations to the sample components provided with the product.
Chapter 4, “Customization using Lotus Component Designer” on page 129, takes the
customization goals further and shows you how to build a custom component from scratch.
Note: Specific files and resources used within this chapter are available for download from
the IBM Redbooks FTP Site. For details on how to download this material, refer to
Appendix C, “Additional material” on page 279.
© Copyright IBM Corp. 2007. All rights reserved.
85
3.1 Overview of customizations to be accomplished in this
chapter
In this chapter, we create all the sample applications provided with Lotus Component
Designer and review the technologies used within each sample. After becoming more familiar
with the tool we pick one sample and customize its look and feel to meet the design standards
of ITSO Cool company. After completing our design modifications we deploy this component
to our portal server and make it available on a server page.
Now that we know how to deploy single components the next step is to assemble a reusable
piece of design containing pages and components that can be used by multiple
organizational units in your company. This we call a template. From a template, multiple
instances can be created named composite applications.
3.1.1 Value to the developer
Developers coming from other design tools like Notes Designer, VisualBasic, or similar
script-based tools can now create components for portal by using LCD.
In the context of the ITSO COOL scenario, developers will learn how to install and configure
Lotus Component Designer. We show how to create the sample applications and how easy it
is to modify these samples, getting more practice with Lotus Component Designer.
Developers will learn as well how to connect to the XML document datastore, and we
introduce the methods for deploying as well as removing components.
3.1.2 Value to the user
For the users, the ability to quickly build, customize, and deploy components using Lotus
Component Designer allows for companies to quickly and effectively surface applications in a
Portal environment. Earlier applications can be given a more intuitive, consistent user
interface. Ultimately, users can be more productive, as they now have access to applications
and information via a single, consistent interface within Portal Express.
Going forward, companies have greater choice on how to access their critical business
applications.
3.2 Lotus Component Designer 6.0
Lotus Component Designer is a visual script-based tool that helps developers create new
applications that provide a rich user interface and supporting business logic without writing
Java code. The intuitive integrated design environment allows script developers, like IBM
Lotus Domino Designer or Microsoft Visual Basic® developers, to use their existing skills and
quickly be productive. Lotus Component Designer provides the ability to drag-and-drop
controls to define the user interface, script-level programming for business logic, and easy
application data definition with a built-in XML schema editor. These capabilities enable
developers to build a complete end-to-end application with one tool.
Lotus Component Designer is very well suited for building collaborative ad-hoc applications.
Ad-hoc applications, which are sometimes referred to as situational applications, are
applications that can be quickly implemented by people with domain knowledge to address a
86
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
specific business problem. Some examples are an expense reports application, a project
management system, or a discussion forum.
Lotus Component Designer enables Domino developers to easily transition their
development skills to WebSphere Portal now and to Notes 8 and Lotus Expeditor in its next
release. Component Designer uses the same application development philosophy as Domino
Designer. To provide Domino developers with the tools they need, Domino Designer 8 will
include an entitlement to Component Designer. This is the first step towards an eventual
convergence between these two tools.
With LCD, you can:
򐂰 Quickly create collaborative XML document-based applications including UI, business
logic, and data store definition.
򐂰 Easily define an XML document store by using the built-in schema editor or importing an
existing schema.
򐂰 Add page-level security to control what level of access users have to documents.
򐂰 Implement business logic using JavaScript and high-level interfaces like @functions and
simple actions.
򐂰 Create JavaScript code using a robust script editor, debug code using a JavaScript
debugger, and store code in reusable script libraries.
򐂰 Create portlets that access data in Lotus Domino, RDBMS, XML files, and Web services.
򐂰 Easily create custom controls by combining controls or importing JSF, that can be re-used
across applications.
򐂰 Customize the runtime behavior for individuals through the use of roles.
򐂰 Allow new applications to be easily customized by defining points of variability at the
component level.
򐂰 Provide inter-portlet communication through support for property broker.
򐂰 Easily implement Ajax functionality for capabilities like type ahead or partial page
refreshes without having to write code.
򐂰 Easily customize the portlet user interface through UI control properties or using standard
HTML and style sheets.
򐂰 Add People Awareness function into portlets.
򐂰 Quickly iterate over multiple designs by one-click deployment to WebSphere Portal.
3.2.1 Business value
Lotus Component Designer provides unique values that make it a first choice for developing
components for IBM Portal family. The unique highlights are:
򐂰 Visual scripting design environment
LCD provides developers with a WYSIWYG script-based development experience that
allows them to see their application UI as they are working. UI controls can be dragged
and dropped onto the page and then parameters can be set to tailor their characteristics.
By providing a visually intuitive experience, developers who are used to developing this
way (Domino, Visual Basic, and so on) can build complex portal applications using
JavaScript.
Chapter 3. Introduction to Lotus Component Designer
87
򐂰 Integrated data definition tools
LCD allows developers to build collaborative applications that utilize an XML document
store that is defined using an XML Schema Document (XSD). The XML document store
can be created and then associated with page controls or vise versa. This gives
developers flexibility when they are choosing how to create their applications. If business
requirements change, a developer can easily change the schema and re-deploy the
application. Component Designer’s one-click deploy automatically creates or modifies the
XML document store along with all the other parts of the application, which speeds the
iterative development process.
򐂰 Complex business logic and data access through scripting
LCD allows developers to implement event-driven business logic using JavaScript. A set
of interfaces allows scripts to access the XML document store, document data, and
metadata. Developers are provided with a script editor and debugger to implement scripts
and script libraries for storing code as a reusable asset. LCD also allows the use of XPath
expressions to access data in its XML documents.
3.2.2 Developer audience for Lotus Component Designer
Lotus Component Designer provides a visual script-based developing environment that well
suites developer experienced with script-based development tools like Lotus Script,
JavaScript, visual basic, or similar scripting languages.
Different data sources like Web services, XML documents, XML Files, and Lotus Notes
Databases relational databases can be accessed by using the intuitive interface and support
developers to provide sophisticated applications in a fast time to value approach.
3.3 Concepts and terminology for Lotus Component Designer
This section provides an overview of the features and functionality of Lotus Component
Designer 6.0. It begins with an initial overview of the workbench and the design elements.
88
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
When you open a component with Lotus Component Designer, you work within an overview
called the Workbench. Figure 3-1 illustrates the various portions and functional areas of the
Lotus Component Designer Workbench. The remainder of this section describes the detailed
features and functionality of each workbench function.
Designer Navigator
Connection Explorer
Outline View
Database Schema
palette
Canvas
Properties View
UI Controls palette
Event View
Problems View
Images palette
Figure 3-1 Functional areas within the Lotus Component Designer Workbench
The functional areas within the Workbench are:
򐂰 Designer Navigator
The Designer Navigator is where you access and manage components and design
elements. By default, the Designer Navigator is located on the left side of the Lotus
Component Designer window. You can create new components, expand or collapse the
list of components by clicking the top bar, expand or collapse individual components by
clicking the component’s top bar, and expand and collapse design element categories by
clicking the plus and minus signs. You can also organize your components into working
sets for easy access.
Chapter 3. Introduction to Lotus Component Designer
89
Elements contained in the Designer Navigator are:
– Components
These are collections of pages, schemas, scripts, and images that comprise a single
portlet in the Portal Server.
– Pages
Pages are used for visualizing the data in functions of the component. Pages can be
populated by design elements provided in the Designer Navigator. These are parts of
Workplace Designer that let you create and modify components visually.
򐂰 Connection Explorer
The Connection Explorer displays connections to XML document stores, relational
databases, and Domino databases where component data is stored. You can create
global connections to new data stores and databases (meaning the connections can be
used by any component), and you can edit stored data in the Connection Explorer.
򐂰 Canvas
The canvas is where you view and edit pages and other design elements. You can access
any of the following editors when working in the canvas:
–
–
–
–
–
–
–
–
–
–
Page editor
Schema editor
View query editor
Relational query editor
Script editor
Style sheet editor
Property editors
Web services adapter
Connection
Component
Activity in the canvas determines what is displayed in the Properties view. For example, if you
are working with a user interface (UI) control in a page, as soon as you click that UI control in
the page editor, the Properties view displays the properties for that UI control.
򐂰 Outline view
The Outline view provides a hierarchical representation of the XML source code in pages.
You can click the individual nodes in the Outline view to navigate through the page and
update properties in the Properties view. You can also drag and drop elements in order to
rearrange sections and change the sequence of elements.
򐂰 UI control palette
This is for presenting all available UI controls. UI controls are visual elements that allow
users to work with data in a form. UI controls include edit fields, buttons, drop-down lists,
and links.
򐂰 Database Schema
The Database Schema palette contains relational database schemas available to the
currently selected page or panel, and all schema tables and columns. You can create
relational queries by dragging and dropping tables and columns from the palette to the
page or panel.
򐂰 Image palette
The images palette contains all the images you have added to the component in which
you are currently working. You can drag and drop images from the images palette onto
pages.
90
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
򐂰 Properties view
The Properties view is located at the bottom of the IBM Lotus Component Designer
window and contains individual tabs that you can click to display a set of options. Since
each page and UI control has it own unique set of properties, the tabs and options within
those tabs change according to what is currently selected. For example, when viewing a
list of pages, if you click the name of an individual page, the Properties view displays
general information about the page, such as the name of the page, the author, and the
date it was created. If you double-click the name of the page, the page opens in edit mode
in the Lotus Component Designer canvas, and a new set of tabs appear in the Properties
view. These tabs change depending on what is currently selected in the canvas, for
example, the entire page or an individual UI control.
򐂰 Events view
The Events view is where you create events for components, pages, and user interface
controls. You can use the Events view to attach simple actions or scripts to events. Events
are organized into categories for easy access. When writing scripts, you can create
server-side or client-side events. You can specify options for updating pages after events
occur, including performing partial updates for a portion of page elements based on
Asynchronous JavaScript and XML (Ajax) technology. When writing simple actions, you
can write actions that perform a pre-programmed activity that can be modified by
arguments. You can also create groups of simple actions.
򐂰 Problems view
The Problems view displays errors, warnings, and other information about IBM Lotus
Component Designer resources. These messages are generated when you build the
Eclipse workspace. For example, if you save a page that contains syntax errors, the
Problems view will display those errors.
The Lotus Component Designer functions and features are discussed in more detail
throughout the following chapters as we build our sample application.
Note: The intention of this chapter is to provide an overview of the design features, while
subsequent chapters go into much greater detail within the specific context of the sample
application.
3.3.1 Explanation of the design elements shown in the Navigator
The Workplace Designer design elements are components, pages, UI controls, and events.
Components
Components are collections of pages, user interface controls, schemas, scripts, images, and
styles that make up one or more portlets. By default, each component provides an XML
document database for you to store your data. You build components in Lotus Component
Designer, deploy them to the target platform as portlets, and add them to applications. Users
can then access applications with a browser and work in Lotus Component Designer portlets
that are part of the application.
Components are stored in your Eclipse workspace in a folder with the same name as the
component. For example, if you create a component named ProjectManager, all of the files
that are stored on your machine for that component are located in a folder called
workspace/ProjectManager, where workspace is your Eclipse workspace.
Chapter 3. Introduction to Lotus Component Designer
91
You can create new components from scratch or you can use one of the sample applications
as a starting point for the new component. You can write scripts to associate with events in a
component. To do this, select a component event, then write a script for that event.
The types of element in a component are:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Component options
Pages
Custom controls
XML schemas
View queries
External data
Resources
Composite application
Note: The term component is sometimes referred to as a portlet. This is because the
component that you create with Lotus Component Designer is deployed as a portlet to a
Portal server.
Component options
Here you define the basic settings for the component like the error page, localization options,
and custom control settings. For the portlets you can set the portlet name, the default page,
edit page, help page, and for the datastore if the store should be shared across multiple
instances of a component and the detailed access level per role.
Pages
Lotus Component Designer pages contain the text and user interface controls that users
interact with while working with application pages. You can design the look and functionality
of pages before you deploy them to the target server or servers. You can set properties for
the entire page as well as for each of the individual design elements that you add to the page.
You can create a data source for each page, and also for each panel within a page. Data
sources define how user data entered in the page or panel is stored, and how stored data is
displayed.
Custom controls
Create custom controls for your components. A custom control is a collection of user interface
controls that are stored as a single object. Similar to Lotus Domino Designer subforms,
custom controls are design elements that you can create once and add to multiple pages.
When you update a custom control, every page that uses that custom control automatically
gets updated with the changes. This saves you design time because you do not have to
update each page separately.
Common uses of custom controls include adding a company logo to business documents or
adding mailing label information to mail and memo pages. A custom control can be a
permanent part of a page or can appear conditionally, depending on the result of a formula.
For example, you might offer users a choice of custom mail pages with different graphics and
styles for various types of mail messages, such as memos, alerts, or letters.
XML schemas
When a component stores data in an Lotus Component Designer document database, it
means that a user has entered data in a control or a script has dynamically generated it, and
that the page has been submitted. At the time the page is submitted, Lotus Component
92
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Designer generates an XML document to contain the data, and then stores that document in
the database. The XML schema can be viewed and edited from the XML Schemas view.
View queries
You can display data from an Lotus Component Designer document database in views by
creating a view with an associated view query. View queries query Lotus Component
Designer document databases and can then populate views with the returned data. Both
views and view queries contain columns. View query columns are bound to elements in
particular XML documents stored in the database, and return data from those documents.
You bind view columns to view query columns, and then the view columns display data
returned by the view query columns that they are bound to.
External data
External data comprises:
򐂰 Connections
Relational database connections contain information required for a component to connect
to a relational database. Local relational connections are part of particular components
and cannot be used by other components. To see local connections in the Designer
Navigator, expand the component in the Designer Navigator, double-click Component
Options, and then in the Component Options tab check Show external data options.
򐂰 Relational queries
You can exchange component data with a relational database by creating a relational
query in Lotus Component Designer. Relational queries specify columns in an existing
relational database. After you have created a relational query you can bind controls to
database columns, and you can query the database and populate views with returned
data.
򐂰 Web Service adapters
Each Web service has a Web Services Description Language (WSDL) file that describes it
in XML format. Applications such as Lotus Component Designer components use WSDL
files to interact with the Web service. Web service adapters are Lotus Component
Designer design elements that create connections with Web service WSDL files.
Resources
Resources are:
򐂰 Style sheets
Lotus Component Designer provides several options for working with style sheets. For
example, you can either create your own style sheets or import existing ones from your
local machine and add them to pages within your component. You can also group your
favorite style sheets into style sets, categorize style classes, and map style classes to UI
controls.
򐂰 Images
Maintain a collection of images that you import into components. You can import JPEG,
BMP, GIF, TIF, and PNG images from your local file system. After you import images, you
can add them to pages or to other controls.
򐂰 Script library
You can create your own script libraries or you can import existing script libraries. Here
you can view a list of the script libraries in a component. The list opens in the canvas. You
can select a library in the list, and information about that library displays in the Properties
tab at the bottom of the Lotus Component Designer window.
Chapter 3. Introduction to Lotus Component Designer
93
Composite applications
Composite applications are:
򐂰 Script
Create JavaScripts and associate them with events that run when a component instance
is created or removed, or when members are added and removed from your component.
All scripts can be found in this view.
򐂰 Actions
Defines the actions that are triggered when portlets publish properties that get received by
another portlet. Examples of actions include changing or refreshing component pages and
redirecting the current page to a Web site. In composite applications, the following steps
must take place before an action can occur. The user interacts with a portlet in some way,
for example, inputting a value and then clicking a Submit button. A script runs and
publishes the property value to the IBM WebSphere Portal property broker. The property
broker finds the portlets that are listening for the property value and tells them to perform
the requested action.
򐂰 Wiring properties
Define the properties that portlets will use to exchange information using the IBM
WebSphere Portal property broker. The property broker transfers instances of these
properties and their values to and from portlets to initiate actions.
򐂰 Roles
Create user roles that your portal administrator can map to template roles on IBM Portal
Server. After your administrator maps roles on the server, when users access the
component, their template roles are mapped to Lotus Component Designer roles.
Templates have only two default roles, users and administrators, so by default you can
use only two of the five roles available with Lotus Component Designer. To employ more
Lotus Component Designer roles, you can create new template roles and map the Lotus
Component Designer roles to them. You can reference roles through scripts. You can also
assign database privileges to different roles that are defined in your component.
򐂰 Parameters
Set parameters that identify property values for application templates on the target
platform. These parameters are available to users creating and editing templates and
applications.
3.4 Installing Lotus Component Designer and working with
included sample applications
The following section discusses how to install Lotus Component Designer and introduces you
to the sample applications included with the product.
3.4.1 Installing Lotus Component Designer
Lotus Component Designer is included in the IBM Portal 6 Express package at no extra
charge but is not installed by default with the Portal installation process. If you do not have a
Portal Express 6 Media Kit, but do want to install LCD, there is a trial version available at
http://www.ibm.com for download.
Locate the installation file for Component Designer, for example,
ComponentDesigner6Tool.exe. Once you locate this, click this file to execute the installer.
94
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Installation of Component Designer is straightforward. Simply follow the prompts within the
Install Wizard prompts.
There are two options to choose from when installing Lotus Component Designer, depending
on whether Eclipse 3.2 is already installed on your workstation:
򐂰 If you already have installed Eclipse 3.2 or later you can add Lotus Component Designer
as a plug-in or install Lotus Component Designer, including Eclipse 3.2 next to your
existing installation.
򐂰 If you have not installed Eclipse 3.2 on your workstation, Lotus Component Designer will
install Eclipse 3.2 and the Lotus Component Designer Plugin on your workstation.
Once you have complete the installation wizard for Lotus Component Designer, you will see
this icon on the desktop
. Click this to launch Lotus Component Designer.
3.4.2 Launching Component Designer for the first time
Once you launch Component Designer, you will be presented with a dialog requesting the
path to your workspace. Accept the default value or change it as desired. Next you are
presented with the Component Designer Welcome window, as shown in Figure 3-2.
Figure 3-2 Component Designer Welcome window
Chapter 3. Introduction to Lotus Component Designer
95
From within this Welcome page, you can choose from different starting options. If you hover
the cursor over the icons, you can explore the different choices, including:
򐂰 Overview
򐂰 New Features
򐂰 Samples (This is where you can get details for the sample application we work with
throughout the remainder of this chapter.)
򐂰 Tutorials (all you need to know about component designer)
򐂰 Web resources
򐂰 Workbench
For the sake of the example in this chapter, we recommend first launching the Workbench by
clicking the Workbench icon.
3.4.3 Installing sample applications
To install sample applications:
1. Start the Lotus Component Designer.
96
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. Continue by clicking the IBM Lotus Component Designer icon in the lower left corner and
the Workbench will open. You will be presented with a Workbench similar to that shown in
Figure 3-3.
Figure 3-3 Workbench
3. In the workbench click File → New → Component.
4. Enter a name and select the option Start with sample application.
Chapter 3. Introduction to Lotus Component Designer
97
5. Select the Contact List Sample, as shown in Figure 3-4. The description will be filled. If
you want to have a different description change the text and click OK. The component will
now be imported into the Workbench.
Figure 3-4 Creating a new component starting from the contact list sample component
You may repeat these steps for each of the sample components you wish to work with.
3.5 Modifying the contact list sample
After having introduced the basic elements of the Lotus Component Designer, we now start
working with the tool. For the sake of this exercise, we add minor design changes to the
content list component to align it to our ITSO Cooling Company corporate image standard.
We do this in a step-by-step manner, making it easy to follow.
98
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
3.5.1 Step-by-step: adding image resources to your application
This section describes how to add the necessary image resources to your sample
component.
1. Open your Lotus Component Designer workbench (if it is not already open) and navigate
to the Contact List sample component. (See Figure 3-5.)
Navigating to the
contact list
sample
Figure 3-5 Navigating to the contact list sample
2. From within the Design Navigator, expand the Contact List Sample component, then
expand the branch of the Resources Folder until you see an icon for Images.
Chapter 3. Introduction to Lotus Component Designer
99
3. Double-click the Images top-level resource (twisty) (Figure 3-6).
Double-click the images resource
List of image resources
Figure 3-6 Double-click images resource
4. Once you have double-clicked the Images resource, you will see the list of image
resources. For reference, this should look like Figure 3-7.
Figure 3-7 List of image resources
100
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5. Now click the import image icon and enter the location of the companyLogo.gif and the
description.
Note: The logo used in this example (companyLogo.gif) is provided as a downloadable
file via the IBM Redbooks FTP site. For details on how to download this material, refer
to Appendix C, “Additional material” on page 279.
Figure 3-8 Importing the company logo
6. Click OK and the logo is now in your Image Resource list.
7. Repeat this sequence to import the horzGradient.gif file into your component as well.
3.6 Editing the contact list sample component
Within the following sections, we describe how to edit the contact list sample component. This
actually involves three parts of the component, namely editing the:
򐂰 ContactsView page
򐂰 ContactsDisplay page
򐂰 ContactsEdit page
Chapter 3. Introduction to Lotus Component Designer
101
Each of these component elements can be navigated to using the Designer Navigator, as
shown in Figure 3-9.
Navigating to different elements
within the component
Figure 3-9 Different elements within the Contacts List component
3.6.1 Step-by-step: editing the ContactsView page
To edit the ContactsView page:
1. Using the Designer Navigator, navigate to the Pages folder in your ContactList
component.
102
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. Open the ContactsView page for editing by double-clicking it (Figure 3-10).
Figure 3-10 ContactsView page
Chapter 3. Introduction to Lotus Component Designer
103
3. Before changing anything, look at this page. It consist of various design elements, which
are shown in the Outline view. An example of the Outline view for this page is shown in
Figure 3-11.
Tip: The best way to explore a page is by using the Outline viewer in the lower right
corner of the workbench. Here you have insight into all elements of the page.
Figure 3-11 on page 104 illustrates an outline of the page elements.
Figure 3-11 Outline view showing design elements within the page
Notice that if you click an element in the outline view, the Canvas and the Properties views
change automatically to show the details of the chosen page element. We strongly
recommend that you take some time to explore the page structure and its elements.
Additionally, refer to both 3.3, “Concepts and terminology for Lotus Component Designer”
on page 88, and the Lotus Designer online help to once again review the design element
types.
4. Now we add two rows to Table1. Table1 is the table within the contact page where all
content resides.
Tip: If you are not sure which portion of the element constitutes Table1 within the page,
just click Table1 in the outline view and the table will be marked in the canvas.
104
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5. To add the rows simply move your mouse pointer below the icon and right-click. The menu
shown Figure 3-12 in should pop up, allowing you to select to add rows.
Figure 3-12 Menu for manipulating tables
6. Click the menu option to Insert Row Above and a row will be added to the top of the
page. Repeat these steps to add a second row. Now your page should look like
Figure 3-13.
Table Rows added
Figure 3-13 Two table rows added
Adding the customized logo
To add the customized logo:
1. In the first cell of the table (upper left corner) we add our ITSO Cooling logo
(companyLogo.gif) we imported in step 5 on page 101.
Chapter 3. Introduction to Lotus Component Designer
105
2. To add the logo, click the image icon in the UI Controls palette and drag it to the upper
right cell. In the pop-up dialog window that appears, choose the companyLogo.gif and
click OK. (See Figure 3-14.)
Figure 3-14 Dragging the image control
Once you click OK, you will see the logo appear in the upper left cell of the table
(Figure 3-15).
Figure 3-15 Having added the ITSO Logo
Move {text1} and change attributes
In this section, we modify the text attributes to better match the corporate identity.
1. Click the {text1} element and cut it by clicking Ctrl+X or by right-clicking. Navigate to the
table cell just to the right of the logo cell, and paste {text1} there.
106
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. To change the color and other attributes for this text:
a. Click {text1} and go down to the Properties view.
b. From within the Properties window, choose the Style and Font tabs and change the
font to Tahoma® and the size to 20 (Figure 3-16).
Figure 3-16 Manipulating text properties
3. For creating a customized color, click the font color button. Choose Define Custom
Colors and add 198 for red, 36 for green, and 54 for blue.
4. Click Add to custom colors to add this color and click OK. Now you have changed the
font attributes of the text.
Figure 3-17 Defining the custom color for the text attributes
5. Finally, after you define this custom color (Figure 3-18), you will see the text in the new
custom color.
Figure 3-18 Text modified with custom color
Chapter 3. Introduction to Lotus Component Designer
107
Final table modifications
To make the final table modifications:
1. Delete the default icon.
To delete the default icon, shown in Figure 3-19, navigate to column 1 row 3 and click the
icon. Select the icon and delete it by clicking Ctrl+D or the option in menu you access by
right-clicking.
Figure 3-19 Select this icon and delete from the table
2. Merge cell columns in row 2.
To merge the cell columns in row 2, navigate your cursor to the first cell of row 2. Highlight
the cells in both column 1 and column 2. Both cells should now be marked. Go to the
Table tab in the menu line and choose Table → Merge Cells.
3. Add horzGradient.gif to merged cells.
This step places a red horizontal line across the upper section of the card.
To add the horzGradient.gif, click the image icon in the UI Controls palette and drag it to
the merged cells. In the pop-up that appears choose the horzGradient.gif and click OK
(Figure 3-20).
Adding a horizontal line across the top of the card
Figure 3-20 Adding a horizontal line across the top of the card
108
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
4. Click horzGradient.gif and go down to the Properties view.
Choose Image and change the width option from auto to percent in the drop-down list.
Enter 100 for the percent value, as shown in Figure 3-21.
Figure 3-21 Change width option
5. Remove the line feed.
The last step is to remove one of the line feeds above the New Contact button. To do this,
click one of the line feed symbols and delete it by pressing Ctrl+D or selecting Delete in
the pop-up menu you get when right-clicking (Figure 3-22).
Figure 3-22 Line feeds - one needs to be deleted
6. Save and preview your work.
Now we have modified the Contacts view to align to the standard corporate image. Save
your change by selecting File → Save.
Chapter 3. Introduction to Lotus Component Designer
109
To preview the changes you have made so far, you can click the Preview Web button located
at the bottom of the canvas. Your preview should look similar to Figure 3-23.
Preview Web tab
Figure 3-23 Preview Web view
3.6.2 Step-by-step: editing the ContactDisplay page
For editing the ContactDisplay page we perform similar steps as with the ContactsView page.
Note: While this section outlines the individual steps, it does not provide quite as much
detail as the steps outlined in 3.6.1, “Step-by-step: editing the ContactsView page” on
page 102, though it provides the basic steps. If you need additional detail, refer to3.6.1,
“Step-by-step: editing the ContactsView page” on page 102, for additional information.
110
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Steps for editing the ContactDisplay page
To edit the ContactDisplay page:
1. Modify the table to add more rows.
From within the Designer Navigator, navigate to the ContactDisplay page, then
double-click this page to open it. You will see a page similar to Figure 3-24.
Figure 3-24 ContactDisplay page
2. To add the two additional rows for placing the banner, click just to the lower right of the
existing icon. (If you highlight the icon, click slightly lower so that the cursor is simply
placed in the table. Notice in the menu at the top of the window that a table menu should
appear.) See Figure 3-25.
Adding rows
Figure 3-25 Adding rows
3. Add the ITSO logo.
To add the logo, click the image icon in the UI Controls palette and drag it to the upper
right cell. In the pop-up dialog window that appears, choose the companyLogo.gif and
click OK. At this point, the company logo will appear in the upper right-hand cell.
Chapter 3. Introduction to Lotus Component Designer
111
4. Move Contact Details text and change attributes:
a. In this section, we move the text element next to the logo, and modify the text attributes
to better match the corporate identity.
b. Click Contact Details to select the text element. Cut it by pressing Ctrl+X or by
right-clicking and selecting Cut. Navigate to the table cell just to the right of the logo
cell, and paste Contact Details there.
c. To change the color and other attributes for this text, click Contact Details and go
down to the Properties view.
d. From within the Properties window, choose the Style and Font tabs and change the
font to Tahoma and the size to 20 (Figure 3-16 on page 107).
Figure 3-26 Manipulating text properties
5. For creating a customized color, click the font Color button. Choose Define Custom
Colors and add 198 for red, 36 for green, and 54 for blue.
6. Click Add to custom colors to add this color and click OK. Now you have changed the
font attributes of the text.
Finally, after you define this custom color, you will see the text in the new custom color
(Figure 3-27).
Figure 3-27 Text modified with custom color
112
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
7. The final step consists of merging table cells and completing minor table modifications.
a. Select the table cells containing the logo, Contacts Display text, and select Merge
Cells from the table menu.
b. Choose Image and change the width option from auto to percent in the drop-down list.
Enter 100 for the percent value, as shown in Figure 3-21 on page 109.
Figure 3-28 Change width option
8. Remove the line feed.
The one last step is to remove one of the line feeds above the Edit Contact button. To do
this, click one of the line feed symbols and delete it by pressing Ctrl+D or by right-clicking
and selecting Delete (Figure 3-22 on page 109).
9. Use the Preview tab in Designer to judge the end result. Your preview for ContactDisplay
page should look like Figure 3-29.
Figure 3-29 Preview of modified Contact Details Display page
3.6.3 Step-by-step: editing the ContactEdit page
For editing the ContactEdit page we perform similar steps as with the ContactsView page.
Chapter 3. Introduction to Lotus Component Designer
113
Steps for editing the ContactEdit page
For editing the ContactEdit page we perform similar steps as with the ContactView page.
Note: While this section outlines the individual steps, it does not provide quite as much
detail as the steps outlined in 3.6.1, “Step-by-step: editing the ContactsView page” on
page 102, though it provides the basic steps. If you need additional detail, refer to 3.6.1,
“Step-by-step: editing the ContactsView page” on page 102.
Steps for editing the ContactEdit page
To edit the ContactEdit page:
1. Modify the table to add more rows.
From within the Designer Navigator, navigate to the ContactDisplay page, then
double-click this page to open it. You will see an image similar to Figure 3-30.
Figure 3-30 Displayed page
114
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. To add the two additional rows for placing the banner, click just to the lower right of the
existing icon. (If you actually highlight the icon, click slightly lower so that the cursor is
simply placed in the table. Notice in the menu at the top of the window that a table menu
should appear.) See Figure 3-31.
Adding rows
Figure 3-31 Adding rows
3. Add the ITSO logo.
To add the logo, click the image icon in the UI Controls palette and drag it to the upper
right cell. In the pop-up dialog window that appears, choose the companyLogo.gif and
click OK. At this point, the company logo appears in the upper right-hand cell.
4. Move Contact Details text and change attributes:
a. In this section, we move the text element next to the logo, and modify the text attributes
to better match the corporate identity.
b. Click {label4} to select the text element. Cut it by pressing Ctrl+x or by right-clicking.
Navigate to the table cell just to the right of the logo cell, and paste {label4} there.
c. To change the color and other attributes for this text, click {label4} and go down to the
Properties view.
Chapter 3. Introduction to Lotus Component Designer
115
d. From within the Properties window, choose the Style and Font tabs and change the
font to Tahoma and the size to 20 (Figure 3-32).
Figure 3-32 Manipulating text properties
5. For creating a customized color, click the font Color button. Choose Define Custom
Colors and add 198 for red, 36 for green, and 54 for blue.
6. Click Add to custom colors to add this color and click OK. Now you have changed the
font attributes of the text.
Finally, after you define this custom color, you will see the text in the new custom color
(Figure 3-33).
Figure 3-33 Text modified with custom color
7. The final step consists of merging table cells and completing minor table modifications:
a. Select the table cells containing the logo and Contacts Display text, and select Merge
Cells from the table menu.
b. Choose Image and change the width option from auto to percent in the drop-down list.
Enter 100 for the percent value, as shown in Figure 3-21 on page 109.
Figure 3-34 Change width option
116
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
8. Remove one of the line feeds above the OK and Cancel buttons. To do this, click one of
the line feed symbols and delete it by pressing Ctrl+D or by right-clicking (Figure 3-22 on
page 109).
9. Use the Preview tab in Designer to judge the end result. Your preview for ContactDisplay
page should look like Figure 3-35.
Figure 3-35 Preview of modified Contact Details Display page
At this point, you have performed the necessary modifications.
3.6.4 Exporting the modified ContactList sample
Now that we have modified our ConactList component, we make a backup by exporting the
component to the file system. If necessary, this export file can be imported back into Lotus
Component Designer and contains all elements contained in your component.
Chapter 3. Introduction to Lotus Component Designer
117
To perform the export:
1. Open the Navigator and right-click the ContactList component. In the pop-up click
Export. See Figure 3-36.
Figure 3-36 Click Export
2. Choose the directory on your file system where you want your component to be saved to
and click OK. (See Figure 3-37.) Optionally, you can change the file name of the saved
version of the file. This makes sense if you want to have a backup or versioning approach.
Figure 3-37 Exporting to the component to the file system
Note: When saving, the file extension for a component is WDC.
As an alternative, you can save your component to a WAR file for remote deployment as a
portlet. In addition, you can create a DDL file as well to create the datastore that relates to
your component.
118
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
3.7 Deploying modified ContactList sample to your portal
server
Deploying the component to the Portal Express server is very easy. In this section, we guide
you through the steps to accomplish the deployment.
3.7.1 Step-by-step: creating a new deployment profile
To create a new deployment profile:
1. To deploy a newly created component, go the Designer Navigator and select Component
Options, then right-click and select Deploy.
Figure 3-38 Select Deploy
Chapter 3. Introduction to Lotus Component Designer
119
2. If you deploy to a Portal Express server for the first time, it is first necessary to set up a
deployment profile. You can do this be selecting the Add button (Figure 3-39).
Click Add to create a new
Deployment Profile
Figure 3-39 Create new deployment profile
120
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
If you have no deployment profiles, click the New button and enter values for the following
parameters (Figure 3-40). On the target platform page enter values for:
–
–
–
–
Deployment profile name
DNS or IP address of your portal server
Portal user ID and password with permission to create portlets
HTTP port of the portal server
Note: If you do not have access to an administrative user ID for your portal or some of
the parameters are unknown to you, ask your portal admin for details.
Target Platform tab
Figure 3-40 Target Platform tab
Chapter 3. Introduction to Lotus Component Designer
121
3. On the other tab, namely the Document Store tab, enter the following values (see
Figure 3-41):
– Your datastore. If you installed the default you must select Custom Relational.
– Select Choose jdbc url connection.
– Driver class = DB2-App.
– DB user and password. The default is wpdb2ins, but this can be different on your
specific portal server.
– Database. The default is wpsdb, but this can be different on your specific portal server.
If you have no user ID for your portal or some of the parameters are unknown to you, you
will need to ask your portal administrator for details.
Document Store tab
Figure 3-41 Document Store tab
122
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
4. Once you have completed all field entries, click Test Profile to check whether you can
connect to your portal server. The user name and password are pre-filled with the initial
values you provided, but you can change both if you want or need to (Figure 3-42).
Figure 3-42 Test Deployment Profile
5. Click OK to continue (Figure 3-43).
Figure 3-43 Test Deployment Profile
Chapter 3. Introduction to Lotus Component Designer
123
If this window appears everything is fine. If a error is returned it might look like Figure 3-44.
Figure 3-44 Test server and document store connections
This indicates whether your portal connection, your datastore connection, or both failed. Your
portal administrator will need to help you to resolve these issues.
Step-by-step: deploying the component to portal server
In our case the test was successful and we are now ready to deploy the component to the
portal server. Open the right-click menu and click Deploy. Select your deployment profile if
you have more then one and click OK (Figure 3-45).
Figure 3-45 Deploy Component
124
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
If the deployment was successful you should have the message box shown in Figure 3-46,
and the component is now installed on the server.
Figure 3-46 Component successfully deployed
Step-by-step: removing a component from portal server (optional)
If necessary, you can remove a component in a similar way. Just click the Undeploy button
located under the Deploy button in the right-click menu. In addition to the parameters
provided in the deploy panel, there is one additional choice to remove the data used by the
component as well. If you remove a component permanently it makes sense to remove the
data as well. If not, you can keep the data and use it after another deployment of the
component (Figure 3-47).
Figure 3-47 Undeploy Component
Chapter 3. Introduction to Lotus Component Designer
125
Step-by-step: adding the deployed ContactList sample to a portal page
The last step in publishing our component to users is to put it on a portal page. As described
in Chapter 2, “Introduction to customization in WebSphere Portal Express” on page 15, we
added a page called orders.
1. Navigate to this page and open the portal palette. Enter Contact in the Search field and
click OK (Figure 3-48).
Figure 3-48 Search for Contact
2. Click the ContactList portlet page and drag the portlet onto the page where a orange line
appears, and drop it there (Figure 3-49).
Figure 3-49 Drag portlet onto page with orange line
126
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
3. To customize the header of the ContactList portlet click the triangle to open the portlet
options menu and choose Personalize (Figure 3-50).
Figure 3-50 Choose Personalize
4. Change the header for the contact list to ITSO cool Contactlist and save the change.
(
Figure 3-51 Change header
Now we have finished our customization and your component should look like Figure 3-52.
Figure 3-52 Finished customization
Chapter 3. Introduction to Lotus Component Designer
127
Try the component and add some contacts to the list. Check whether all pages look alike with
the design changes we made and whether everything works fine. Once your have completed
these tasks you are ready to go deeper into developing components with Lotus Component
Designer.
3.7.2 Summary
In this chapter we touched upon the following topics:
򐂰 We discussed the benefits to developers and users of Lotus Component Designer. We
provided an overview of the workbench to introduce the different parts of LCD and we
talked about the design elements that can be used in LCD.
򐂰 We discussed how to install LCD with or without Eclipse already in place and
demonstrated how easy it is to set up the example components that ship with the product.
򐂰 We customized the ContactList component with images we imported, and we changed the
layout of the pages to adapt to the ITSO Cooling Co. corporate image.
򐂰 We exported the component to the file system, set up a deployment profile, and deployed
the component to a portal server.
򐂰 Finally, we set up a page in portal server and applied the component to this page,
modified the parameter for the heading, and viewed our first customized component
coming from within LCD.
128
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
4
Chapter 4.
Customization using Lotus
Component Designer
In this chapter we show how creating custom components to meet specific company needs
can be easily done using Lotus Component Designer.
Continuing with the ITSOCOOL company scenario, we create a component that has two
parts, and will benefit two divisions. For the sake of this example, we focus on helping the
sales department and customer service personnel.
We create a simple purchase ordering component, which allows the sales department to
document each order they have taken. This component is created using the standard method
of data storage known as the docDB.
The inventory management team creates a stock control component that uses other data
sources, such as Web services, and a relational data base.
We finish this chapter showing how we can use the information entered by the stock control
component to assist when creating an order, using Ajax.
Note: Specific files and resources used within this chapter are available for download from
the IBM Redbooks FTP Site. For details on how to download this material, refer to
Appendix C, “Additional material” on page 279.
Note: For information about how to install Lotus Component Designer, and for basic
information about working with components, also refer to 3.3, “Concepts and terminology
for Lotus Component Designer” on page 88, and 3.4, “Installing Lotus Component
Designer and working with included sample applications” on page 94.
© Copyright IBM Corp. 2007. All rights reserved.
129
4.1 Overview of custom application to be built in this chapter
By the end of this chapter, we will have built a simple purchase ordering system, using the
docDB data store (Lotus Component Designers default data store), deployed it to portal, and
included it on the ISTOCOOL company portal page.
We will have created a stock control system where the stock items will be stored in a
relational database (using the DB2 database bundled with Portal Express). The list of
available items that can be added to the stock control system will be retrieved using a Web
service. We will have also shown how users can very easily add their own JavaScript to
control the behavior of a control and enforce specific fields to be filled in, and introduced
some of the available controls developers can very quickly make use of.
4.1.1 Value to the developer
Developers will learn about creating components from scratch, using a few different data
sources such as Web services, relational databases, and the default data store, docDB.
Along the way, developers will see how to attach simple actions (or custom JavaScript) to
specific controls including an Ajax control. We also make use of custom controls, which can
greatly enhance the speed and consistency of creating end-to-end solutions.
4.1.2 Value to the user
For the sake of this ITSOCOOL scenario, this application provides a new unified interface to
an earlier system.
Benefits to the sales department and customer service personnel
In keeping with the scenario, the sales department and customer service personnel benefit
through a unified interface, and no longer need to log into a separate stock control system to
see what is available. The new interface also allows for specific controls and filters to make
their work more efficient. For example, the new purchase ordering system allows sales team
members to start typing the name of the product they want to order and a drop-down will short
list their options based on this.
Benefits to the inventory management team
In our scenario, the stock controllers need to keep a list of the stock in their already existing
database.
The new stock control component reads this database and provides a page for adding new
records or editing existing ones. Through the use of a Web service, stock controllers no
longer need to connect to their suppliers’ product list manually. Instead, when they go to add
a new product to the stock control system, they will be able to choose from a specific list of
products, retrieved from a Web service. They can then save the newly added product to the
stock control DB.
4.2 Preview of application components we2 build in this
chapter
The following figures illustrate what the completed application components look like when
deployed to Portal Express.
130
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Figure 4-1 illustrates the purchase ordering system, showing the order list.
Figure 4-1 Preview of the purchase ordering system, showing the order list
This shows the main page of the purchase orders management center where users are
shown a list of all current orders, categorized by the customer the orders are raised against.
Along the top are three buttons, of which the first two are of interest in this chapter, New
Order and Remove Selected. The latter one is straightforward. It removes any orders from
the system that have been selected (by means of a check box made available on each order).
The first button provides a means of creating a new order. When clicked, the purchase
ordering system order entry/edit page (Figure 4-2) is displayed. This page opens as a blank
form when opened via the New Order button, but also serves as a means of editing an
existing order when one of the links on list of orders is clicked.
Figure 4-2 Purchase ordering system order entry/edit page
Those are the very basics of the purchase ordering component. The other component being
developed in this chapter, which will in fact supplement the data in the purchase ordering
component, is the stock control center where available stock items will be displayed from a
Web service and used as a means for adding new stock items to the system.
Chapter 4. Customization using Lotus Component Designer
131
The following pages are for the stock control system. Figure 4-3 is the stock control list page
where users will be presented with a list of stock they currently hold.
Figure 4-3 Preview of the stock control list page
When a user clicks the Add button, Figure 4-4 is the window they will see, the order entry
window where a list of available items will be presented based on the selected supplier. Each
product displayed will have a Select button, which fills out the stock item form for the user. All
that users need to do is select the product and enter the quantity and save.
Figure 4-4 Preview of the order entry window
But first we explore the purchase ordering system, building it from the ground up.
132
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Important: For the sake of our illustrative example in this paper, we perform the
customizations while logged in as an administrative user (wpadmin), having the highest
level of access rights to the system.
In an actual production environment, you would not simply use full administrative rights for
all changes and customizations. Instead, you need to work with the portal administrator to
determine necessary access rights and permissions to perform the changes required.
Within the scope of this paper, we do not cover portal administration. Instead, refer to the
Administering section of the Portal Express Information Center at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
4.3 Building the purchase ordering component
Note: For information about how to install Lotus Component Designer, and for basic
information about working with components, also refer to 3.3, “Concepts and terminology
for Lotus Component Designer” on page 88, and 3.4, “Installing Lotus Component
Designer and working with included sample applications” on page 94.
When you start Lotus Component Designer for the first time you will be faced with an
introduction window, which provides you with useful links to:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Overview
What’s new
Tutorials
Samples
Web resources
Link to the workspace (where we create our first component)
Click the Workbench link, where we will create a component from scratch.
Tip: At any point you can view the welcome page by selecting Help → Welcome, from the
menu.
4.3.1 Creating a new component
Like most Integrated Development Environments (IDEs), there are often a few ways to do
common tasks. For the remainder of this chapter, we reference the menus. That said, there
are often other means of achieving the same, such as finding an equivalent tool bar button,
and in some cases, an option is available by right-clicking while in the editor or Designer
Navigator.
Chapter 4. Customization using Lotus Component Designer
133
To create a new component, select File → New → Component. You will be presented with
the New Component window, as shown in Figure 4-5.
Figure 4-5 New Component window
Enter the name of your component. In this example we use PurchaseOrdering. Leave the
default option of start with blank component and click OK.
Note: The main focus of this chapter is creating components from scratch, so we do not
use any of the sample applications. For more information about using these, see
Chapter 3, “Introduction to Lotus Component Designer” on page 85.
You should now see the window in Figure 4-6, which shows the various parts of your new
component.
Figure 4-6 Parts of your new component
134
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
There are many sections created for each component, and at first glance they may seem
overwhelming. This is not the case, as you will soon see. These sections simply cater for all
the needs a developer could have for any component, and by no means does each section
need to have content relevant to your component. Here is a brief description of what these
different sections are for:
򐂰 Component options
This section is for applying settings to the over all component, such as which portal pages
should initially appear, localization aspects such as what languages are supported,
custom control settings, portlet details, and database options.
򐂰 Pages
All standard component pages appear under this section. Each time you add a page, this
is where you will find it.
򐂰 Custom controls
This section contains all custom controls created. A custom control is simply a grouping of
other controls put together in such a way that it can be used in multiple places. For
example, if your component required a login section on several different pages, you could
create a custom login control that simply consisted of the various parts needed to make up
your login section, such as the user name and password labels, edit boxes, a login button,
and a cancel button. This custom control could then be dragged onto any page. Create it
once, use it many times. Custom controls are very powerful and can be used in many
ways, as we see in the later in this chapter.
򐂰 XML schemas
As mentioned briefly earlier on, Lotus Component Designer can make use of many
different data sources. For advanced users, it is even possible to add in completely new
kinds of data sources. However, this section deals with the default data store, which is
XML documents stored in a relational data base. The structure of the data to be used in
the component is defined in schemas. Here we define the fields, how they relate to each
other, and the kinds of data they store. We create a schema further on in this chapter,
where you will see this in action.
򐂰 View queries
One of the most useful controls on the palette is the view control. This allows data from the
data store to be listed out in a table form. In order to provide better control over the data
that will be displayed in these views, view queries are used that define what fields are to
be shown. Where the view queries becomes very handy is when you need to define the
ordering (sorting) of particular fields (or columns from a table context), filtering, and
defining the type of data and how it should be displayed, summary rows (such as sum,
minimum maximum average, and so on).
򐂰 External data
This section is for making use of other forms of data such as relational databases and
Web services.
– Connections
This section shows the connections that defined on this component for connecting to
relational databases.
– Relational queries
Simply put, this is the relational database equivalent to view queries. Although
currently it does not have the same number of options as the view query, it is still very
powerful and more or less interchangeable with a view query, which in itself is great as
it makes life easy when changing a component over from using a relational database
to using the docDB.
Chapter 4. Customization using Lotus Component Designer
135
– Web service adapters
Web services have been made easy in Lotus Component designer. There are a
number of ways to create your Web service. It can be as simple as pointing to a Web
Service Definition Language (WSDL) file on a server and the tool will create all the
available adapters for you, ready for you to make reference to them in your application.
Other approaches include supplying a local copy of the WSDL file or making use of a
Universal Description, Discovery and Integration (UDDI) to find the Web service and
retrieve the WSDL file.
򐂰 Resources
Like any custom component made, there will always be a need to have custom resources,
such as style sheets, images, and scripts. This section holds all of these.
– Style sheets
All Cascading Style Sheets (CSSs) files that a component references are held here.
This does not include the default styles applied to controls. In Lotus Component
Designer, as a default, controls added to a page inherit a default style. This default
styling references the style sheets defined on Portal Express, which means that as the
styling changes through out the Portal Express server, those changes will also be
reflected in Lotus Component Designer components. If no style class is applied to a
control, then the default style will be applied to the control. It is possible to disable
default styling of controls from the Styles tab on the Properties panel.
CSS files can be added to a component and reference the style class by any of the
controls. Any CSS files added to the component appear in this section.
– Images
All images added to the component will be shown here. We add images to our
components, so you will see this in use later in the chapter.
– Script library
As well as adding JavaScript to various parts of controls directly, developers can
create handy libraries of JavaScript, which can be made available on the client or the
server.
򐂰 Composite application
Composite applications are a powerful feature of Portal Express. Lotus Component
Designer makes good use of these features, providing ways to make use of the various
aspects of composite applications such as wiring components together and providing
actions that can be fired on composite events.
– Script
JavaScript intended for composite application collaboration is shown here.
– Actions
Actions that are to be fired for particular events are shown here.
– Wiring properties
Properties defined here can be referenced by other components or portlets deployed to
the sever. These properties can be used to expose specific values within the
component. For example, when a link to an stock item is clicked, properties could
expose the stock items identifier. Another component on the same page could then
use this value to show other aspects of that item.
136
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
– Roles
It is possible to define roles in Lotus Component Designer to either restrict access or
hide and show data or even controls (for example, showing only certain data when a
manager logs in, and hiding various controls when a restricted user logs in).
– Parameters
Parameters are useful for defining the behavior of the overall component. These
parameters, once specified, are created here.
4.3.2 Creating the purchase order main page
The main page of the purchase ordering component mainly consists of a view control that
displays all the orders in the system. As mentioned earlier, Lotus Component Designer
document database stores data as XML documents in a relational database. To make use of
this, we need to define how the XML documents will be structured. To define the XML
documents, we use schemas. The schema allows us to define what fields we want out XML
document to contain, and the types of data each field. After creating the schema, we create a
view query. The view query allows us to control the data that is presented to the view control
on the page. We also make use of the custom control as a means of creating a page template
that makes creating subsequent pages faster and more consistent in look and feel. As we
progress through the chapter, we come back to enhance this basic page.
Creating the schema
The purchase ordering system is kept intentionally simple. As such, we only add the most
basic fields needed for a purchase order (make, model, description, order date, and the
owner of order — the full list is shown below).
Select XML Schemas, right-click, and select New XML Schema. The New XML Schema
window appears, as shown in Figure 4-7. Give the XML schema the name PurchaseOrders
and click OK.
Figure 4-7 New XML schema
Chapter 4. Customization using Lotus Component Designer
137
The schema is created with the default root element PurchaseOrders, with a single child
element, named element0, as shown in Figure 4-8.
Figure 4-8 Schema is created with the default root element called PurchaseOrders
The first thing we need to do is rename element0 to something more meaningful, so
right-click element0, select edit, and change the value to make. To add the other fields,
right-click the PurchaseOrders element, and you can choose from two of the options, Insert
Element or Append Element. Each of these have a sub menu, which allows you to either
insert or append a child element or a sibling element. Since we have selected the parent
element, insert or append are our only options. So select Append Element → As Child and
add the rest of the fields, setting their types (as indicated in braces):
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
138
customer (string)
make (String)
model (String)
description (String)
quantity (integer)
orderDate (date)
dueDate (date)
unitPrice
salePrice
orderOwner (String)
stockOwner (String)
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Your schema should look like Figure 4-9.
Figure 4-9 New purchase order schema
Now that the XML schema has been created, we can save this and close it. The next thing we
want to create is a view query. This will allow us to present the data to the view control.
Creating the view query
In order to control what data we wish to display on our view, how it should be ordered, and
which documents from all the documents available should actually be shown, we use a view
query to control the presentation of data. A view query is mapped to a schema and allows you
to select which fields should be retrieved from the database. There is a lot that can be
specified on the view query to affect the presentation of data from the XML document
database to the view, most of which is out of the scope of this chapter. However, we see the
very basics of its operation now, as we create a view query that our Orders view control uses
to present a list of orders placed by the sales personnel. To do this, select View Queries
from the Designer Explorer, right-click it, select New View Query, and name it allOrders.
Chapter 4. Customization using Lotus Component Designer
139
Now we want to select the schema that this view query will be bound to. While the AllOrders
view query page has focus, you should notice a Properties panel below the page. This
property panel is divided up into sections to help find the detail you are interested in quickly.
Right now we are interested in the detail shown on the Basics tab of the properties panel. In
the Schemas box, select the PurchaseOrders schema, as shown in Figure 4-10.
Figure 4-10 select the PurchaseOrders schema
On the View query page, you will see the title of the view query, AllOrders, the schema its
bound to, PurchaseOrders, and a single column. More on this shortly. To configure a view
query, the first thing that needs to be done is to specify which fields from our XML document
data, which we defined in our XML Schema, should be added. The view query presents the
these fields as columns, to help visualize its purpose, which is typically to display data in
tablature form.
140
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Now we need to add the columns we are interested in showing on our view, preferably in the
order in which we want them to be displayed. Initially, the view query is created showing one
column that is currently not bound to anything. So let us first bind this to the customer field of
the schema by selecting the column and selecting customer from the Data drop-down menu,
as shown in Figure 4-11.
Figure 4-11 Binding the first column to the customer field
Note: If you do not see any fields appear when you expand PurchaseOrders in the Data
drop-down menu, it is most likely because the modifications made to the PurchaseOrders
schema have not been saved. Once saved, you should see the fields appear.
We can now add the remaining fields and bind them to the appropriate field on the schema.
To add a column to the view query, right-click a blank area of the view query page and select
Insert Column or Append Column. The only difference between these options is where the
column will appear. Insert adds the column before the currently selected column, and append
adds it after the currently selected column. Add nine columns, even though we have eleven
fields defined in our schema (there is no need to display all the fields — the description field
would take up too much space, so we leave it out).
Chapter 4. Customization using Lotus Component Designer
141
Now each column needs to be bound to a field in the schema. For clarity’s sake, we bind the
columns of our view query to the fields in the schema in the order in which we wish them to
appear on the view control. We have bound the first column already to the customer field.
Proceed through the rest of the columns and bind them to the appropriate field in the schema,
as shown in Figure 4-12. The columns in Figure 4-12 have been wrapped so as to fit them on
a page. They do not typically wrap around like this.
Figure 4-12 Columns have been wrapped so as to fit them on a page
Let us also set the view query to be sorted by the date it is due to our customer. This can be
done by selecting the DueDate column and from the Property Panel. Set the Sort to
Descending. Now that we have our data and view query set up, we can create the main page
of our purchase ordering system.
Creating a custom control
Instead of just adding the controls we want directly to the page, we create a custom control
first, which we can then re-use for each subsequent page, cutting down on the amount of
work we need to do overall. Custom controls are generally used for building specialized
controls for a specific purpose, like a generic tool bar, or for creating a panel that might
display a specific set of controls that would be used in many places. There is really no limit to
the uses of custom controls, and as you will see, using them to create your page template can
142
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
be quite useful. Although creating the custom control might seem like a lengthy process, once
you go through it once it will go quickly after that, as its very simple. By the end of this sub
section, you will have a custom control that should look something like Figure 4-13.
Figure 4-13 Preview of the custom control you will create
To create the custom control, right-click Custom Controls for our purchase ordering
component and select New Custom Control. Name it PageTemplate and click OK.
This control is going to be used to help lay out all the pages of our control. Let us use a table
to position everything. Tables are useful for positioning controls on a page so that controls
consistently line up in each column, and can be spaced out as desired.
On the right side of Lotus Component Designer is the UIControls panel, which lists all of the
common controls. Each page is built by dragging these controls on to the page where you
want them. The layout follows similar rules to that of Web pages, in that controls all appear
one after the other from the top left of the page out and downwards. We use a table to have
better control over the layout.
Tip: The UI Controls panel is divided in to several sections, Select, Select Control, Core
Controls, Containers, and Custom Controls. Clicking any of these headings expands and
collapses that section, which can help you find what you are looking for when dealing with
many controls or if you do not have much room on your window. Also, right-clicking any
one of the headings in the UI Controls section provides you with a way to control the layout
of the controls within this panel.
Drag and drop a table onto the page. You will find the table control in the Containers section
of the UI Controls panel. Initially, it will have only two columns and two rows. Add another two
rows by clicking one of the table cells, right-clicking, and selecting Append Row(s). This
presents you with a simple dialog prompting you to specify how many rows you wish to
append. The default is one. Increment to two and click OK.
Chapter 4. Customization using Lotus Component Designer
143
Now we want to set the properties of the different cells in our table. Below is a list of the cells,
what their functions will be in our component, and what properties we want to set on them.
򐂰 Top left cell
This is where we put our company icon. We want this to be center aligned and we want to
place the icon in this cell. First select the cell and from the All Properties tab of the
Properties panel, scroll down to the Format section and expand it (if its not already
expanded). In there you should see the align property. Click the value column of the align
property and type in center.
Tip: The All Properties tab in the Properties panel reveals every property that can be
set for the currently selected control. Other tabs do not always make use of every
property supported by a control, as doing so would make for a very cluttered set of tabs.
Typically, only the most commonly used properties appear on the standard tabs. Use
the All Properties tab to get the most out of your controls if you cannot find what you are
looking for in the standard tabs.
Next we want to add the company logo to the template so that it appears on all the pages.
Drag across an image control and you will be presented with a dialog prompting you to
select your image, as in Figure 4-14.
Figure 4-14 Add the company logo to the template
144
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Click Add Image and you will be presented with another dialog where you can specify the
location of your image on the file system along with other options such as the name you
wish to give this image within your component (Figure 4-15). The only information that is
required is the location of the original image. Giving the image a new name or a
description is optional.
Figure 4-15 Giving the image a new name or a description
Click the Browse button to browse the file system for the image your wish to use. Images
along with other resources used in this chapter can be downloaded as outlined in
Appendix C, “Additional material” on page 279. When you have selected the image, click
OK and you will be returned to the initial Select Image dialog. As this is the first image to
be added to the project, it will definitely be selected, but for future images, make sure to
select the correct image from the list of available images before proceeding. Click OK
again and you should now see the image appear in the page.
Tip: Now that you have imported an image on to the page, it is useful to know that all
imported images appear by default in the Images panel (lower right panel, below the UI
Control panel). You can just drag these images straight on to the page instead of
adding an image control to a page and then selecting the image.
Chapter 4. Customization using Lotus Component Designer
145
Your page should now look like Figure 4-16.
Figure 4-16 How your page should now look
򐂰 Top right cell
This shows the title of this component. For example, in this component we label it
purchase ordering system, but we do not do this in the template, so that we can change it
in one place and it will be reflected through out the component. This makes more sense
when we start referencing this custom control in another component further on in this
chapter. To provide the consistency we want, let us apply the styles we want here, so that
all users of this custom control inherit the correct look and feel.
From the Table Cell tab of the Properties panel, change the width units to percent and
enter 100. Now select the Font sub tab and set the font to Tahoma, set the font size to 20,
the color of the font to Red (to fit in with the theme changes we made in an earlier
chapter), and click the bold button. Again, set the alignment of the cell to center, as
described for the top left cell.
We have styled the cell appropriately. Now we need to add an editable area so when this
custom control is used in other pages, we can incorporate our own control into the custom
control. Editable areas are only used on custom controls, and by themselves have no
visual properties. They are positioned in custom controls to provide place holders. When
the custom control is used on a page, controls can be dropped onto these place holders.
This is very useful, as it means that a custom control can be further customized by the
page it is being used in. Without the ability to use editable areas, using a custom control
for a template would be impossible. To add editable areas onto our custom control, drag
an editable area from the UI Controls panel on to the page and label them appropriately.
Find the editable area control on the UI Control panel and drop it into the top right cell. To
facilitate the usage of editable areas, each one can be given a name. By default these are
called facet_1, facet_2, and so on. With the newly created editable area selected on the
page, go to the Editable Area section of the Properties panel and change the name and
facet name to something meaningful. This will help remind you on subsequent pages
where you use this custom control, what each editable area is for.
Note: Its more important to set a facet name, as that is what you see on pages making
use of this custom control.
146
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Your page should now look something like Figure 4-17.
Figure 4-17 How your page should now look at this stage
򐂰 Second (from the top) left and right cell
We use this to separate the page head from the page body by having a line appear just
under the heading. We place this line in the second row. Let us merge the two cells. To do
this select both cells (hold the left button down while moving across both cells). Once
selected, hover over one of the box anchors. You should see the mouse pointer change to
arrows (either an arrow move icon, or a two-arrow shrink/stretch icon). If you right-click at
this point, you see that the context menu contains additional options for altering the table.
One of the last options is to merge the selected cells. Select this option.
Now set the line on the cell. With the merged cell selected, from the Properties panel
Table Cell tab, set the cell height to be 10px. Then on the style background tab, click the
Browse button to the left of the Image URL edit box, and select horzGradient.gif. Images
along with other resources used in this chapter can be downloaded as outlined in
Appendix C, “Additional material” on page 279. Now you probably notice that we have
multiple lines as background to this cell, which we do not want. To clean this up, set
Repeat to repeat-x and Position to Center Left. Your window should look something like
Figure 4-18.
Figure 4-18 Set Repeat to repeat-x and Position to Center Left - your window should look similar
Chapter 4. Customization using Lotus Component Designer
147
򐂰 Third (from the top) right cell
This is the location for all our buttons on each page, so all we want to do from a template
point of view is add an editable area to this cell, this time naming it menuBar.
򐂰 Bottom right cell
This is the main body of the page. When we use this template on another page, it will be in
this area in which we add the main content for the specific page. We do not need to
specify any styling for this, as the default is fine. For consistency though, set the width to
100% as we did for the top right cell. The alignment is fine. It defaults to the left, so all we
need to do here is to add the editable area. Add the editable area and call it body.
Now the custom control is completed. You should have something similar to Figure 4-19.
Figure 4-19 Page template complete
Creating the View page
Now that we have all we want set up for the component we can get on with creating the main
page. Select the Pages section on the Designer Navigator, right-click, select New Page, and
call it StockList. You do not need to choose any of the other options on the New Page dialog
at this point. When creating other pages, these options will come in useful.
You will get a blank page, much the same as when you create the custom component, but
this time we first drag on the custom control we just created. So from the UI Control panel,
drag the PageTemplate custom control on to your page. Initially the control will look much as
it does on the custom control page. However, now you see green dots beside each of the
editable areas we created in the custom control. These green dots are areas in which you can
drop other controls into (or just type into).
Click the ComponentTitle type in Purchase Ordering System. You will notice that the styling
you set on the custom control is affecting the text you have just typed in. By adding this
custom control to each page you create, ensure that they all have the same consistent look,
with no extra effort. And at any point if you decide that the styles we have set so far are
suitable, you can always go back and change them (at any point) and see those changes
reflected in all your pages. We see this used later in this chapter.
148
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Now it is time to add the view control to the page. You will see it in the Containers section of
the UI Controls panel. Drop that onto the page over the body editable area green dot. You will
notice that you are presented with a Select Query for View dialog (Figure 4-20).
Figure 4-20 Select Query for View dialog
In the Type of query drop-down box, select the view query option, and in the View query
drop-down box, select the view query we created earlier in this chapter, AllOrders. You will
notice that by default, all the columns are selected. Leave them all selected and click OK.
With the view control selected on the page, go to the View section (or tab) of the properties
panel and set the width of the view to 100%. Your page should now look something like
Figure 4-21.
Figure 4-21 Preview of how your page should look at this stage
We have a little bit left to do on that page but for now let us create the Order Item page, where
new orders can be created or existing ones can be edited.
Creating the Data Entry page
This is the page used for creating new orders (documents) and editing existing ones. At this
point we keep it simple and provide a simple set of edit boxes for entering in the data for each
Chapter 4. Customization using Lotus Component Designer
149
order. Later in this chapter we revisit this page and enhance the functionality. But for now let
us get it working. At the end of this section you should have a page that looks something like
Figure 4-22.
Figure 4-22 Preview of how your page should look
Create a new page, as we just did in the previous section, and name it OrderItem, only this
time, when the New Page dialog appears, we select a schema to be used. Select the Use an
existing XML schema radio button and choose the PurchaseOrder schema. Click OK.
Again, add the pageTemplate custom control and label the edit areas in the same manor as
we did for the OrderList page.
Now to add the controls to this page. Firstly, add a table control to the body editable area.
This helps us lay out the controls. Change the table to have six columns and five rows, and
set the width of the table to 100%.
In the first column, add the labels (you can add label controls that provide extra functionality
such as associating a label with its corresponding control). So for now, let us just type into the
cells. The second, fourth, and sixth columns contain the actual controls that we bind to the
data store (more on that later).
In the first column, add the following (in order):
򐂰
򐂰
򐂰
򐂰
򐂰
Customer
Make
Model
Due Date
Quantity
In the second column, add edit boxes to the first three and the fifth cells, and a date time
picker to the fourth cell (you find it near the bottom of the list of core controls).
Tip: After adding the first edit box you can copy and paste this control to the rest of the
appropriate cells, instead of dragging each one on to the page.
150
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
In the third column type:
򐂰
򐂰
򐂰
򐂰
򐂰
Order Owner
Stock Item Owner
Order Date
Unit Price
Sale Price
In the fourth column add edit boxes to each cell (Description).
Now in the last column we want to add a multiline edit box, but we want it to span four of the
columns. So before adding the control, select the four cells, either by selecting them with the
mouse, or select the first cell, hold the Shift button and click the down arrow three times. Hold
the mouse over an anchor point of the selected cells and right-click. One of the last options is
Merge Cells. Choose this. Now add the Multiline Edit Box, and while its selected drag it to
fill the merged cells.
Tip: You can also resize a selected control by holding down Ctrl+Alt and using the arrow
keys to increment the control size by one pixel, or by holding down Alt+Shift, and using the
arrow keys you can increment the control in increments of 10 pixels.
Your page should now look something like Figure 4-23.
Figure 4-23 Preview of how your page should look at this stage
Chapter 4. Customization using Lotus Component Designer
151
Now we need to bind the controls to the data source. This is simply done by selecting a
control. Let us start with the customer control. Select the customer edit box and on the Data
tab of the Properties panel, set document as the data source if it is not already set, and
select the customer field from the Data Binding drop-down menu, in much the same way as
you did when binding the columns of the view query to the fields in the schema (Figure 4-24).
Figure 4-24 Binding the columns of the view query to the fields in the schema
Do this for the other controls, binding them to their respective field in the schema. All that is
left now is to add the buttons to save or cancel the adding or editing of the order.
Drag a table onto the menuBar editable area and remove one of rows. Now add a button to
each one of the cells. Select the first button and change the label to Save, and set the width to
55 pixels (for consistency). Similarly, label the second button to Cancel and set its width to 55
pixels. At this point, the buttons do nothing. We have to set what should happen when one is
clicked.
As with all controls in Lotus Component Designer, there are many kinds of events that can be
set on them. These events can be sever-side events or client-side events. Client-side events
are always JavaScript, but server-side events can fall into one of two types, JavaScript or
simple actions. These simple actions make associating actions with controls very easy and
quick to configure.
To define the actions we want to attach to each button, select the Save button. Next to the
Properties panel you should see the Events panel.
Attention: If you ever accidentally close a panel or changed the panels around and wish to
return to the default state, you can always click the Window menu and select Reset
perspective. Perspectives are the term given to the selection of panels and their positions
on the designer window. You can move these panels around by dragging the Panels tab
and dropping it where you choose. You can even save your layout as a new perspective. If
you do close one or a panel goes missing, click Window → Show View and select the
view you are missing, and it will reappear on current perspective.
152
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
On this panel select the onclick event from the list of events on the left side of the panel, and
select Simple Actions.
Figure 4-25 Select onclick event from list of events on left side of the panel and select Simple Actions
The panel should look something like that of Figure 4-25. Click the Add Action button and on
the dialog that appears, select basic from the Category drop-down (it should appear as basic
by default). From the Action drop-down, select Save Data Sources. You will notice that the
area below the two drop-down lists changes based on your selection. For Save Data Sources
the only additional information needed is the page that you wish to open upon successful
execution of the action. In other words, if the document saves successfully, the specified
page will be opened next. If the page does not save (if some validation fails, or a required
field was not set), the same page will reappear. We have not set any such constraints on this
page, so the specified page should always appear after the Save button has been clicked.
Figure 4-26 Dialog that appears for add action
Chapter 4. Customization using Lotus Component Designer
153
You will notice that dropping down the Name of page to open next contains a list of all the
pages we have created. Select OrderList and click OK. Now do the same for the Cancel
button, only this time select the Open Page option from the Actions list. Set the name of the
page to open to OrderList and ignore the other options. We visit some of these very shortly.
Click OK and you are done. The OrderItem page is complete and should look like
Figure 4-27.
Figure 4-27 Preview of how the OrderItem page should look at this stage
We mentioned earlier that we have a few small pieces of OrderList to finish off. We can finish
this off now. Open the orders list and in the same manor as we did for the OrderItem page,
add a table and two buttons to the menuBar and label them New Order and Delete Selected
Orders, respectively.
With the New Order button selected, add an open page simple action, only this time, we set
the target document to be new document (Figure 4-28).
Figure 4-28 Set the target document to be new document
The last option on this dialog is to set the document ID. This is useful in other situations where
you want to open an existing document. To open up a specific document you need to specify
the documents ID, which is what this option is for.
154
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Note: Every document stored in the DocDB data store has an associated document ID that
uniquely identifies it from all others. This document ID can be useful when writing
server-side JavaScript to reference a specific document or when creating value bindings.
The view control does this all for you, but if you were listing out the documents of a view
query using a repeat control or a dataTable control, this document ID would come in very
useful. More information about how to reference the document ID and what can be done
with it can be found in the Help pages, found from the Help menu.
For the Delete Selected Orders button, add another simple action. This time select
Document from the Category drop-down, and then select Delete Selected Documents from
the Action drop-down. This requires you to select the view that this action is to be associated
with. It should default to viewPanel1, as that is the name given to the first view added to any
page (unless you specify your own name for the control). Additionally, we have the option of
setting the confirmation text, so let us set that to something like Are you sure you want to
deleted the selected Orders? and click OK (Figure 4-29).
Figure 4-29 Setting confirmation text
Chapter 4. Customization using Lotus Component Designer
155
Next we want to alter the appearance of the view to group all orders by customers, add live
name awareness to the stock owner and order owner columns, set the formatting of the date
fields, and add check boxes to the rows. Most these options are just some simple final
touches to the page, which, as it is, will work fine. But we want to explore some of the things
that can be done to the view. So select the first column (Customer) and on the View Column
tab of the Properties panel you should see lots of options for how the column should appear
(Figure 4-30).
Figure 4-30 View Column tab of the Properties panel
The view is a significant control and takes a lot of the work out of displaying documents or
records in a way that is consistent with views on other portlets in Portal Express. So it is
worthwhile to briefly go over what these properties do.
򐂰 Value allows you to specify the kind of field to display. The supported options are Text (just
plan text); html, which allows you to display content as html, allowing you to provide more
elaborate content; and, finally, Live Name, which is used in conjunction with Sametime,
providing same-time connectivity, showing you when a person is online, and allowing you
to chat or mail the person.
򐂰 Checkbox adds a check box to the start of the selected column for each row. This is useful
for doing things like deleting the selected documents.
򐂰 Icon allows you to add an image to the cell. Where this might be useful is for indicating the
state of a record. Instead of setting a static value for the image, you could set a JavaScript
value binding for the value of the image, returning a different image based on the state.
For example, if listing e-mails, the icon could return the path of a new mail or read mail.
򐂰 Show values in this column as links does exactly that. Instead of text you get a hyperlink.
When this option is selected, you can select what mode this document is to be opened in,
either read-only or edit mode. The page that will be opened can be specified on the data
associated with the view. By default for docDB documents the page used to create the
page is the page that will be used to view the document when this link is used.
򐂰 Category Column allows you to group the columns based on the value of that column.
Optionally, you can specify the images used to expand and collapse the grouped rows.
Important: When using the category column option, it is important to ensure that the data
is sorted. If a categorized column is bound to unsorted data, the categories do not appear
correctly.
156
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
So on that note, we set the Customer column to be a category column. Check the Category
Column check box, and before we move on, open up the orders viewQuery and set the
customer column sort order to be descending.
Go back to the OrderList page, select the make column, and check Show values in this
column as links, and check the checkbox option. This is needed so the Delete Selected
Orders button can find the rows to be deleted. For the OrderOwner and StockOwner, set the
content type to Live Names. Your view should look something like Figure 4-31.
Figure 4-31 Preview of how the view should look at this stage
Deploying the purchase ordering system to Portal Express
We can now deploy the component to our Portal Express server, as we did in 3.7, “Deploying
modified ContactList sample to your portal server” on page 119.
Before deploying the component, let us change the name of the component as it appears on
the Portal Express portlet title bar. On the Designer Navigator panel, you will see component
options. Double-click it to open the page. Along the bottom you will see three tabs,
Component Options, Portlets, and Database. Covering all the options on these three tabs is
out of the scope of this book, but more information about these can be found using the
designer Help pages.
Go to the Portlets tab and in the Portlet Details section and change the name from
PurchaseOrdering to ITSOCOOL Purchase Ordering System. Save and close.
All that is left is to click the Deploy button and add the component to the Sales portal page.
Tip: There are three different ways to invoke the deployment from Lotus Component
Designer. Click the green deploy button on the tool bar, right-click the component in the
Designer Navigator, and select Deploy or use the hot key, Ctrl+F12.
Purchase order conclusion
In this section we covered the basics of creating a simple component within Lotus
Component Designer. We created a schema defining where the data is to be stored, a view
Chapter 4. Customization using Lotus Component Designer
157
query that we used to present the data to the view control, and a custom control that we used
as a template for all pages within the component. We created two pages, one that lists out all
orders on the system using the view control, and we modified it to suit our requirements. The
other page was our data entry/edit page, which we configured to open and create a new
document that would then be stored to the datastore when completed.
The controls we used in this section were the view control, edit boxes, multiline edit boxes,
optionally labels, date time pickers, buttons image controls, and of course we created our
own custom control and used editable areas within it.
4.4 Creating the stock control component
In this section we create the stock control system, which in the ITSOCOOL scenario must tie
into a relational data store. This component consists of three pages. The main page is much
the same as the OrderList page of the previous section, only instead of using Lotus
Component Designers native DocDB data store, it instead uses a relational data store. In our
case, for ease of configuration, we create a database on Portal Express’s bundled DB2
server. If you have a different, more convenient database available and you know the
specifics for connecting to it through JDBC™, then use it instead.
We use separate pages for adding stock and editing existing stock, that will reuse much of
the same custom components, showing more uses of custom controls. The main reason for
having the two pages, however, is that in the next section where we introduce Web services,
we only want to use the Web services on the page used for adding new stock.
Other areas introduced in this section are the use of custom controls created in other
components and browsing the database from within Lotus Component Designer.
4.4.1 Preview of the stock component you will build
A preview of what you will build here can be seen in the following two figures.
The following pages are for the stock control system. Figure 4-3 on page 132 is the stock
control list page where users are presented with a list of stock they currently hold.
Figure 4-32 Preview of the stock component you build in this section
158
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
When a user clicks the Add button, this is the window they see, the order entry window
(Figure 4-4 on page 132), where a list of available items is presented based on the selected
supplier. Each product displayed has a Select button, which fills out the stock item form for the
user. All that users need to do is select the product, enter the quantity, and save.
Figure 4-33 Preview of the stock component you build in this section
Prerequisites
In order to complete this section, you need to have the STOCK table set up on the
ITSOCOOL database, the instructions for which can be found in Appendix C, “Additional
material” on page 279.
Additionally, you need to have the previous component purchase orders deployed to Portal
Express.
4.4.2 The Stock View page
In this section we discuss the Stock View page.
Chapter 4. Customization using Lotus Component Designer
159
Using the custom control from another component
When we created the purchase ordering system, we created a custom control, which we used
as a template for our pages. Duplicating work is never good, and thankfully we do not need to
duplicate this custom control. Instead we can reference the custom control in the Purchase
ordering system, here in the Stock control system. To do this, first we need to tell the
purchase ordering system to share its custom control with others. Open the Component
Options page again and this time, on the Component Options tab, find the custom control
settings and tick the Share custom controls and resources check box and save
(Figure 4-34).
Figure 4-34 Component options and custom control settings
That is it. Other components can now make use of the custom controls of this page.
Attention: Sharing custom controls does not actually copy resources from one component
to another. It references the original controls, which means that you need to have the
components being referenced already deployed to the server.
Now we get started on our stock control component. Begin by creating a new component.
Right-click the Designer Navigator panel, select New Component, and name it
StockControl. Before we begin creating anything in this component, let us first set up this
component to reference the custom controls we are sharing from PurchaseOrdering. Open up
the Component Options page for the StockControl component, and this time in the Custom
Control Settings section we add a component that will be referenced by this component. Click
the Add button at the bottom of this section and select the PurchaseOrdering component
and save the changes. Now when you create a new page, you will see in the custom controls
section that the pageTemplate custom control is now available to you. If this does not appear
for you, restart Lotus Component Designer so that it picks up the newly available custom
controls for this component. But before we create the pages for this component, let us first
create a connection to the relational data store.
160
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Setting up the relational data store connection
As mentioned in the introduction to this section, for the purposes of this paper, we use the
bundled DB2 server as our database, but this could easily be any other relational database
that allows JDBC connections. See Appendix C, “Additional material” on page 279.
In order to use a relational data store, we need to first create a connection that defines how to
connect to the database. To do this, expand the External Data section, right-click
Connections, and select New Connection.
Attention: If you do not see the External Data section on your component in the Designer
Navigator panel, you have two options. You can select to display the External Data section
for this specific component only by opening the Component Options and on the
Component Properties section of the Component Options tab and ticking the Show
external data options check box. Alternatively, you can make this the default for all
components by going in the Preference from the window menu and at the root of the IBM
Lotus Component Designer section, tick Show external data in new components by
default.
You will be presented with a new New Local Connection window in which the Relational
Connection radio button should be selected by default, which is what we want. Give the
connection a name like ITSOCOOL_DB and click OK.
Next we need to specify the JDBC driver that should be used to connect to the database,
along with the user name, password, and URL. We use the bundled DB2 database, which
requires us to specify our own driver. The driver must be available to both Lotus Component
Designer and on Portal Express. The former we configure shortly, but for Portal Express, this
becomes available when you set up the data source in WebSphere Administration Console,
as outlined in Appendix C, “Additional material” on page 279.
Chapter 4. Customization using Lotus Component Designer
161
Enter in the following for the Connection fields, as shown in Figure 4-35:
򐂰 Driver: com.ibm.db2.jcc.DB2Driver (You need to type this in.)
򐂰 User Name: wpdb2ins (default Portal Express db2 user name, unless changed during
installation)
򐂰 Password: whatever you set for the Portal Express admin password
򐂰 URL: jdbc:db2://<domain name of Portal Express server>:50000/ITSOCOOL
You should have something similar to Figure 4-35.
Figure 4-35 Relational connection parameters
At this point, Designer is still not able to connect to the database. We need to provide
designer with the classpath to the drivers needed to connect to the database. The drivers
used to connect to the DB2 server bundled with Portal Express can be found in the following
location:
<Portal Express Install>/db2/java/
And the files that we are interested in are:
򐂰 db2jcc.jar
򐂰 db2jcc_license_cu.jar
If your Portal Express Server is installed on the same computer as the Lotus Component
Designer, then you do not need to copy the files locally. Otherwise, copy the files outlined
above to the same machine as Lotus Component Designer.
162
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
From the windows menu in Lotus Component Designer, go to the Preferences window and
select the IBM Lotus Component Designer section. In the Default Options sub section, you
will see an Advanced option, which allows you to specify the class path for JDBC drivers.
Click the Browse button and browse to the location of both the jar files indicated above and
click OK. The page should look something like Figure 4-36.
Figure 4-36 Default options for the Component Designer preferences
And that is it — you should now be able to connect to your database from within Lotus
Component Designer and create your relational query based on the tables found in your
database, which is exactly what we are going to do now.
Note: You may have noticed that when creating the connection, it was labeled a local
connection. This is because it is a connection created specifically for this component. You
can optionally create a global connection in much the same manor as outlined above, by
going to the Connection Explorer, which is another tab next to the Designer Navigator tab.
From there you can right-click Connections and create a relational connection (among
other connections also available), which will be made available to all components in your
workspace.
Creating a relational query
In order to be able to access the data in the relational datastore, we must create relational
queries that specify exactly what data we want to reference. Advanced users have the option
of seeing (and modifying) the Structured Query Language (SQL) used in to create the
relational query. This is done by clicking the up arrow button at the bottom of the page. We do
not need to go to such measures, but it is there for users familiar with SQL. To create the
relational query, right-click Relational Queries, select New Relational Query, give it a name
like AllStock, and click OK.
Chapter 4. Customization using Lotus Component Designer
163
Attention: If you get an error at this point, and the relational query fails to be created, it is
most likely because your connection to the relational database is incorrect, or the database
cannot be reached. Another possibility is the in the preferences the wrong jdbc folder was
selected.
For our relational query we want to select all fields in our table and return all records from a
specific table, the STOCK table. To do this, from the Database Schema Palette (which
appears on the right, where the UI Controls panel is), drag the STOCK table across onto the
newly created AllStock relational query. Now select all the columns in the table and save the
relational query. It should look similar to Figure 4-37.
Figure 4-37 AllStock relational query
One additional thing we should do here is set the relational query to return all the stock items
sorted by Supplier. This is done by grouping records on Supplier and setting the sorting order
for Supplier. So with the AllStock relational query still open, go to the Properties panel and on
the Columns tab set the sort type for the first two columns (SUPPLIER and MAKE) to
descending, setting the sort order of SUPPLIERS to 1 and MAKE to 2, as shown in
Figure 4-38.
Figure 4-38 Setting the sort order of SUPPLIERS to 1 and MAKE to 2
164
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Then go to the Group tab and add the SUPPLIER column to the grouping by double-clicking
the first cell of the table and selecting SUPPLIER (Figure 4-39).
Figure 4-39 Go to the Group tab and add the SUPPLIER column
Next when we bind this relational query to a view, we will categorize that view, so if we had
not set up the sorting and grouping, we would not get the correct results on that view.
That is it. We should be able to reference the data in our view, so let us go create one and
reference our new relational query.
Creating the View page
Create a new page, and this time call it StockList, leaving all the other options as is. Click
OK. You should see on the UI Controls panel that the custom control pageTemplate is
showing up. If it is not appearing, see “Using the custom control from another component” on
page 160. Drag the pageTemplate on the page, and add a view to the body-editable area.
The Select Query for View dialog will appear, but this time select Relational Query from the
Type of Query drop-down list. Select the relational query we created in the last section
(AllStock) and leave the default of all columns selected, as shown in Figure 4-40.
Figure 4-40 Select Query for View dialog
Click OK to close that window and, like before, you should see a view on your page. Set the
width to 100%. We need to add buttons (to create new stock entries) and set the page that
Chapter 4. Customization using Lotus Component Designer
165
should be open when a link is clicked on the view, but in order to do those things we need to
specify a page (that right now does not exist). So let us just keep creating the other pages for
now.
Creating a stock item custom control and button bar
As we are creating two similar pages, let us cut down on duplication by creating custom
controls for the common areas of both pages. First let us create a control for entering or
editing the details of a stock item. So create an new custom control called stockItemPanel.
There is a trick to speed up creating data entry pages, which we now use to create this
custom control. To do this we temporarily add a data source to this control. With the custom
control page open and selected, add the relational query to the page. This can be done by
clicking the Add button on the Data tab of the Properties panel and selecting Relational
Query. This will add an entry to the Data Sources list, and should have one entry in it called
jdbc. With jdbc selected, set the name to stockRecord and select AllStock as the relational
data source. Although this step is temporary, as we have similar data sources set on each of
the pages, it does serve a useful purpose. It provides us with a reference to the data we use
with this control. Below the UI Controls panel, you will see a Data panel. When the page has
focus (in our case the custom control), this should show the data sources we have added to
that page. You should see the STOCK table appear on that panel. Drag the entire table
across and drop it on to the page. You will notice that it has just about done the entire job for
us: created labels and edit boxes, contained all the controls in a table for us, and even bound
the controls to the data source. We customize this a little more as we progress but for now,
delete the Edit Box associated with the description and replace it with a multiline edit box. Do
not forget to bind it to the description field of the data source. Also, you will notice that the
labels have been spaced out, which we do not want. So remove the white space from the
labels, that is, change S u p p l i e r s back into Suppliers.
And that is it. Our stock item custom control is complete and should look similar to
Figure 4-41.
Figure 4-41 stockItem custom control - how it should appear at this stage
Remove the data source from the page (by clicking the Remove button on the Data tab of the
Properties panel) and save the page.
Next we want to create the button bar, which will consist of two buttons, one of which will save
the data and return us to the StockList page (Save button), and the other will return us to the
StockList page without saving the data (Cancel button).
Create a new custom control and name it StockItemMenuBar. Drop a table onto the page, and
remove one of its rows. Add a button to each of the cells and label them Save and Cancel,
respectively. With the Save button selected, go to the Events panel and add select simple
166
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
action for the onclick event. Click Add Action, and with the category set to basic, select Save
Data Sources from the Action drop-down menu. Select StockList as the Name of page to
open next and click OK (Figure 4-42).
Figure 4-42 Adding an action and selecting StockList as the Name of page to open next
For the Cancel button do the same, only when choosing the Action instead choose Open
Page and select StockList as the name of page to open (leaving the other options as is). And
that is it. We can now proceed to creating the stock entry page, in which we will make use of
these custom controls.
Creating the Stock entry page
In this section, we create the basic Stock entry page, but we build it in a way that suits the
modifications we will make in a later section where we make use of Web services to supply
the stock information. So initially it might seem odd that we are creating a table with cells we
have no need for, but this will make sense further on in the chapter.
So create a new page and name it StockEntry, leaving all other options as is. The first thing
we want to do is add the data source to the page, which in this case will be exactly the same
data source as we had temporarily added to the StockItemPanel custom control. What is
important here is to give this data source the same name as we did for the custom control so
that our bindings match up. So from the Data tab of the Properties panel for the StockEntry
page, click the Add button, as before, and select Relational Data Source. Give it the same
name as before (stockRecord) and select AllStock as the relational data source.
Chapter 4. Customization using Lotus Component Designer
167
To add the controls on to the page:
1. Drag the pageTemplate onto the page.
2. Drag the StockItemMenuBar custom control onto the menuBar editable area.
3. For the body editable area drag across a table, and drop the StockItemPanel onto the
bottom right cell (the other cells will be used later in this chapter).
4. Type Stock Control Center in for the titleArea editableArea (Figure 4-43).
Figure 4-43 Adding controls to the Stock Control Center page
And that is it. We have our basic Stock Entry page complete. We now create the Stock
Editing page.
Creating the Stock Editing page
This is more or less exactly the same as the Stock Entry page, except that this time do will not
add the table to the body.
1.
2.
3.
4.
168
Create a new page and call it StockItemEditor.
Label the titleArea as Stock Control Center.
Add the StockItemMenuBar to the menuBar editable area.
And finally add the StockItemPanel to the body editable area.
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
You should have a page looking similar to Figure 4-44.
Figure 4-44 Creating a page for editing our stock records
And that is more or less it. In a few clicks and drags and drops we quickly created a page for
editing our stock records.
One thing still remains, however, and that is that we need to specify the relational data
source. Only this time, we want to set parameters on the relational data source so we always
get a single record, and that it is always the correct record. First the view control on the main
page needs to be configured to make these parameter values available for our
StockItemEditor page. By doing this, when a link on the view control is clicked and the
StockItemEditor page is opened, the correct information is made available for the
StockItemEditor relational data source to find the correct record.
Creating the Stock Control Main page
This page lists out the current stock items and shows users what stock is available to sales
personnel, how much of it there is, and of course, who is responsible for it. To create this
page:
1. Create a new page and call it StockList.
2. Drag the pageTemplate onto the page.
3. Set the titleArea editable are to be Stock Control Center.
4. Create the menu bar section:
a. Add a table to the buttonBar area and remove one of its rows.
b. In the first cell, add a button and label it Add Stock Item, and add a simple action to the
onclick event to open a page, this time specifying:
•
•
Name of page to open: StockEntry
Target Document: New Document
c. In the second cell, add another button, setting the button label to Delete Selected
Stock, and add a simple action to the onclick event specifying:
•
Category: Select Document.
Chapter 4. Customization using Lotus Component Designer
169
•
Action: Select Delete Selected Documents.
•
View Name: Select the view we just added, which should be the only one on the
page and called viewPanel1.
•
Confirmation Text: Type in:
Are you sure you want to delete the selected Stock from the system?
5. Add a view to the body editable area, at which point you will be presented with the Select
Query for view window, where you should set the following
– Type of query: Select Relational Query.
– Relational Query: Select AllStock (it should be the only one at this point).
– Ensure that all query columns are selected except the description column.
6. In much the same way as we did for the PurchaseOrder view, we need to customize our
view to make it more useful. Set the following on the View column tab of the Properties
panel for the appropriate column:
– In the Suppliers Column, tick the Category Column check box.
– In the Make column, tick the Show values in this column as links check box, leave
the default of Edit radio button selected, and tick the Check box check box.
– In the Owner column, change the Content Type to Live name.
The page should look similar to Figure 4-45.
Figure 4-45 Preview of the page as it should look at this stage
Getting the StockItemEditor to display the correct record
Now that we have the StockList page completed, we need to configure our pages so that
when a link on the view is clicked, the corresponding record is opened up in the
StockItemEdit page. We do this by using parameters on the StockItemEditor page data
source.
In order to specify parameters for the pages data source, we need a relational query to be
configured specifically to use the parameters, we need to specify those parameters on the
170
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
data source, and we need the calling page to set those parameters. This might sound
complicated, but it is in fact quite simple. There are in fact only three steps to this:
1. Create a new relational query, and on it, specify that the query is to return a record based
on conditions that will be specified as parameter vales.
2. On the StockList page, where users click the stock item links in the view, we configure the
view data to set the significant fields that identify a single record, up onto the request
scope. In our case, this means that our view data source will be set to put the MAKE and
MODEL values of the specific record that was clicked, upon the request scope.
3. Then on the page when we add the relational query we add parameters to the data
source, and bind them to the request scope variables that we expect the view data source
to have set for us when the page is being opened.
Creating a parameterised relational query
This is done in much the same way as for the first relational query, with a few additional
steps, as outlined below:
1. Create a new relational query and call it SingleStockItem. The ISTOCOOL_DB connection
should be selected by default, so click OK to create the relational query.
2. As before, drag across the STOCK table and select all the columns. With the table in the
relational query selected, you can right-click and choose Select All Columns.
3. Select the Conditions tab on the Properties panel to set up the conditions for this query
so that the correct row is returned from the data store. In our database, MAKE and
MODEL are the primary keys, so in order to ensure that the correct row is returned, both of
these must be used in our condition, and will be compared against host variables, which
we set up further on. Your condition table will look like Figure 4-46 when completed.
Figure 4-46 Condition table
To do this take the following steps:
a. Double-click the first column cell and select MAKE.
b. The operator cell should default to =. If not, set it as such.
c. Double-click the Value cell in the bottom of the drop-down list. you should see build
expression. Double-click this option, which should open up an Expression® Builder
wizard.
Chapter 4. Customization using Lotus Component Designer
171
d. On the first page of the wizard, select the Constant - numeric, string or host
variable radio button and click Next (Figure 4-47).
Figure 4-47 Expression Builder wizard
e. On the next page, select String Constant (Figure 4-48).
Figure 4-48 Select String Constant radio button
f. On the third page select the Host variable name radio button and click Finish.
g. For the AND/OR column select AND, at which point you should repeat the steps for the
MODEL field in exactly the same manner, except on the second row of the condition
table do not specify anything for AND/OR.
We have taken a brief glimpse at the Expression Builder, in which there are many options to
craft a query for almost any need. Covering this wizard is out of scope of this paper. For now,
however, our relational query is complete. We should add this relational query to the
StockItemEditor page and configure it to provide the values for the host variables we just
specified in our query.
172
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Configuring the view to set the parameters for the relational query
Now that our relational query is expecting some host variables to be made available, we need
to add parameters to the pages data source that will make these values available. But first we
should add the data source. Open up the StockItemEditor and select the page (as opposed
to a control on the page), and on the Data tab of the Properties panel, click the Add button.
Select Relational data source from the list. With the new data source selected, set the name
to be stockRecord, and set the relational data source to be SingleStockItem.
Now add the parameters to the relational data source. Select the All Properties tab and
scroll down and expand the data section. You should see another data section. This is the
data object set on the page. Inside that you should see a jdbcSdoData entry. Expand this
and you will see all of the available properties, most of which are advanced properties that
can be set on the relational data source. At the bottom of this section you should see another
data entry, which contains only one entry, parameters. When the parameters entry is
selected, you should see a plus and minus button beside the entry, like in Figure 4-49.
Figure 4-49 When parameters entry is selected, you should see a plus and minus button beside entry
We need to add two parameters, one for MAKE and one for MODEL. These parameters
consist of a name/value pair, the name of which matches up with the host variables we
created in our relational query, and the value will contain the relevant value of the stock item
that is to be retrieved. To specify the correct value each time, we need to compute this value,
as the make and model will be different for each link clicked. We do this using computed
values. Computed values are values that are derived from an XPath expression, some
JavaScript, or an Expression Language (EL). More in-depth information about all forms of
computed values can be found in Lotus Component Designers built in help. For now we will
use EL. EL allows us to easily reference variables that are in scope, such as the
requestScope, sessionScope, and applicationScope. We bind our parameter to a
requestScope variable. By making use of the computed field functionality, our parameter
value is evaluated dynamically each time its needed.
Click the plus button. You should see a parameter appear, containing a name and value
property. The parameter property can be configured as follows:
1. Set the name property to be MAKE.
Chapter 4. Customization using Lotus Component Designer
173
2. For the value we want to set a Computed Value, so we get the correct value from the
request scope dynamically. When the value property is selected, you will notice a blue
diamond at the end of the cell. When you click it you get two options, use static or
compute value. Select compute value and a Script Editor window appears. On the
language drop-down select EL and type in requestScope.MAKE, which should look
something like Figure 4-50.
Figure 4-50 Select the compute value and a Script Editor window appears
3. Repeat the steps for MODEL, setting the name to MODEL and the value
requestScope.MODEL from within the script editor.
Important: When specifying EL (or any other) computed values, remember that they are
case sensitive. Failing to observe this will most likely lead to disappointing results.
And that is it, we have specified that our relational query uses some parameters. We have
added the relational data source to the page and added those parameters to the data source.
Now we need to go to our Stock view and tell it to put those parameter values up on the
requestScope (where our parameters know to look for them).
Binding the data entry controls to the relational data source
Open the StockList page and select the view control. From the All Properties tab of the
Properties panel, scroll down to the data section, its data sub-section, and expand as we did
before so that you can see all the properties of the xp:jdbcSdoData object. In that list of
properties, select the detailQueryCols, which allows us to specify the column data we are
interested in. Type in MAKE,MODEL separated only with a comma (without space). Observe the
case and save the page.
Finishing the Stock List page
There are a few loose ends to tie up. The main one is specifying which page to open when a
user clicks the link. This is done on the data tab of the Properties panel, from the drop-down
list of the Open selected record using list. Select StockItemEditor, and that is it.
Deploying the stock control system to Portal Express
We are now ready to deploy the StockControl component to Portal Express. Press Ctrl+F12
to deploy the component. Add it to the Stock page within Portal Express as outlined
previously, this time adding the component to the Inventory page. You should be able to click
the Add Stock Item page and add a new stock item, save it, and see the stock item appear
on the view control on the main page.
174
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
So far we have created a component that is similar in functionality to the PurchaseOrdering
component, with the key difference of it getting its data from a relational data store. We have
made further use of the pageTemplate custom control created for the previous component
and created some of our own, more specific to this component. We have seen the additional
steps that need to be taken to reference a relational data store and the steps needed to
ensure that we get the correct record back for an individual stock item selection. What we
need now is to make use of the earlier repository of suppliers and the products that they
provide, which has been made available by means of some Web services. That way, users
will not be manually entering in product data into our system. Instead, they will look it up and
select the correct item.
4.4.3 Incorporating Web services into the stock control system
In this section we discuss incorporating Web services into the stock control system.
Prerequisites
This section assumes that the StockControl component has been completed in the previous
section, as we now make some additions to it adding in Web services. It is also assumed that
the Web services ear file has been successfully deployed to Portal Express, or to whichever
server suits. The actual location of the Web service is not important. It is only important that
you know its location, and that the Portal Express server can reach it.
Introduction
In this section, we introduce using Web services within Lotus Component Designer. The
ITSO Cool scenario is quite simple. The ITSO Cool company made use of an earlier system
that provided them with a comprehensive list of suppliers, and all the products that the
company would receive from those suppliers. Part of that system provided a means of
connecting remotely to that system using Web services so that other systems could retrieve
this data. To make life easy, we deployed the ITSO Cool Web services ear on the same
Portal Express server. Of course, the location of this Web services is only the difference in a
URL, and instead of setting up a separate server just to host the Web service, it makes sense
just to use the Portal Express server.
We use two of the available Web service calls — one to get a list of available suppliers and
the second to return a list of products given a specific supplier name. In our component, we
modify the StockEntry page so that we are initially presented with a list of suppliers in a
combo box. When we select a supplier, the second Web service is fired to return all products
available from that supplier. We then create a custom JavaScript action that copies the
contents of the selected product across to our Stock Entry fields.
Making use of a Web service from within Lotus Component Designer is fairly straightforward.
There are a few things you need to watch out for, which in due course are pointed out, but in
general it is a simple matter of creating a Web services adaptor. Adding a Web service
adaptor to your page is much the same as with XML document data and relational data
sources. You then bind your controls to the various elements of data that will be returned from
the Web service.
In this section, we introduce the repeat control and show you how to create your own custom
JavaScript actions where no simple action exists to do what we want. We also make use of a
combo box control, populating its contents using a computed expression.
But first, we need to create our Web services adaptor.
Chapter 4. Customization using Lotus Component Designer
175
Creating the Web services adaptors
Creating a Web services adaptor can be done in one of three ways:
򐂰 Specify the URL to the Web Services Definition Language (wsdl) file.
򐂰 Specify a local copy of the wsdl file.
򐂰 Make use of a UDDI directory to locate the wsdl file.
In this section we specify the URL of the wsdl file as our means of creating the Web services
adaptor. First you need the URL to the wsdl file, which should be something like:
http://<domain-name>:10000/ITSOCOOL_WS_Resource/services/SuppliersService?wsdl
Where the port is typically 10000, and the context path of the Web service servlet is
ITSOCOOL_WS_Resources, the Webservices servlet itself is called SuppliersService, and
we want to query for the wsdl file, hence the ?wsdl.
Attention: It is also possible to reference the wsdl file by its path on the deployed
application, but this is not advised. By using the Web services servlet (and not the path to
the actual wsdl file), the servlet amends the returned wsdl file with the correct URL for the
server its running on. By referencing the wsdl file directly, this would not happen, and
although you will get the wsdl file, it may not contain the URL pointing to the Web service.
As a result, the component may never succeed in reaching the Web service.
Right-click Web Services Adapters and select New Web Service Adapter.
You are presented with a window that you are most likely very familiar with now. Give the
Web service a name (Suppliers_Repository) and click Next. You should see the window
shown in Figure 4-51.
Figure 4-51 Web Services parameters
176
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
With the default radio button of Use URL selected, enter in the URL shown previously,
substituting <domain-name> with the actual domain name of your portal server (it should be
the same as what you specified in the deployment profile for server name or address). When
you click Next, the wizard attempts to connect to the Web service and retrieve the wsdl file.
When the wsdl file is retrieved and parsed, the wizard advances to the next window, where
you are shown all of the available Web service calls that are available. We want only two of
them:
򐂰 getSuppliersNames
򐂰 getProductsBySupplier
You should see a window similar to Figure 4-52 with only these two calls checked.
Figure 4-52 Web Service Operations
When you click OK, you should see your newly created Web service adapters under the Web
Service Adaptors section, under the name we gave at the start of the Web Services Adaptor
wizard (SuppliersRespository).
The way Web services work is by sending a request document to a particular Web service
call, specifying the information that is required by that request document. In response, the
Web service sends back a response document containing the data. Both of these documents
are XML documents, and their structures are defined in the wsdl file. When the adapters are
created, the structure of these files is interpreted and presented to us on the adaptor page.
From this we can determine what information needs to be set on the request document and
what kind of information we can expect to be returned.
There is an additional document that has not been mentioned yet, and that is the fault
document. Again the structure of this document is defined in the wsdl file and is the file that is
returned in place of the response document when things go wrong.
Chapter 4. Customization using Lotus Component Designer
177
Let us try invoking the Web service now. Double-click the first adaptor (it should be called
SuppliersServiceSoapBinding_getSupplierNames). You should see a window similar to
Figure 4-53.
Figure 4-53 Invoking the Web Service - clicking the first adapter
On the getSupplierNames adapter Description page (Figure 4-53), you should notice that
there is not much that can be changed or adjusted. This page is more for information than
anything else. The information that we are most interested in is the Parameters section,
where the structures of the request document, response document, and fault document are
presented.
You will notice in the Parameters section for the Request Parameter Schema that one
parameter is expected, the startsWith value. It should be noted that this is a demo Web
service, and as such, the startsWith value has no effect on what is returned (to keep things
simple). So for the purposes of our component we always pass in the value all, as a value is
required for the request document. More important is the response parameter schema, which
tell us what we can expect to be returned. From this we can see that the impl:item will hold
the name of a supplier. As such, we can expect multiple impl:item objects to be returned. This
might not seem very clear from the structure presented, especially when viewed for the first
time. Thankfully, we can see more than this. At the bottom of the page you may have noticed
that this is the first of two tabs, the second one being Test Adapter, which, as the name
implies, allows us to test this adapter, and better still see what does get returned.
178
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Open the Test Adapter tab and you will see to sections (Figure 4-54), the Request Document
and Response Document, with two buttons in between. The most important button here is the
Invoke Web Service button. Click the Invoke Web Service button to see what will be
returned. You should see a window similar to Figure 4-54.
Figure 4-54 Test Adapter tab
In Figure 4-54, you can see the contents of the response document, showing you exactly
what is being returned. This is a basic XML document, which means binding it to our controls
is much the same as we did for the XML Document Data source. It can often be more literal
that we want, but it serves its purpose well and gives use a good indication as to what to
expect back when the Web service is invoked. Here you can see multiple items were
returned, all children of the root element in the document getSupplierNamesReturn.
Let us briefly look at the second Web service call, getProductsBySupplier, and invoke it, and
see what we get back. Do note, however, that the Web service also expects a parameter, and
it does matter that you specify one that makes sense. It expects a valid supplier name, which
we now have because we were returned these values when we invoked the first Web service.
So keep note of one of the supplier names and open the second adapter. Notice how the
structure is a little different. It shows what information needs to be sent in the request
document and all the fields that we can expect to be returned in the response document.
Chapter 4. Customization using Lotus Component Designer
179
Open the Test tab and edit the response document, placing one of the SupplierNames
between the start and end supplierName element. Now invoke the Web service and look at
what gets returned. You should see something similar to Figure 4-55.
Figure 4-55 Results from invoking the Web service
As you can see from the response document, we can expect that the data returned will be
Product items and will contain four fields describing the product. It is this information that we
bind to controls in order to display the products on our StockEntry page. We need to list out
these products on the page one after the other, regardless of the number of items returned.
There are two main ways this can be done — one is by using a dataTable control, which
would present the data in a table, which we have all seen before. Another more interesting
control for doing the same thing is the repeat control. This control is similar in nature to the
dataTable in that it iterates over a set of data. Where these differ greatly is in how the data is
presented. A repeat control is essentially a container that renders its content once for each
row of data, leaving you free to customize the layout of the repeat content as you see fit. So
let us go modify the StockEntry page to make use of this repeat (among other controls) to
display the Web services data.
Modifying the Stock Entry page
You may recall that when we originally created the StockEntry page, we added a table to the
page and only put content in one of the cells. We are now going to use the rest of these cell
for the Web services part.
First we need to add another row and column to the table. Use the insert row and insert
column, as we want to leave the existing data entry controls in the bottom right most cell. You
should now have a 3x3 table. In an effort to make this page more presentable (with all the
information we are about to put on it), we deal with the Web service supplier list on the left
side of the table, and the right side continues to be used for data entry. To make this clear to
the user, we put a separator between these two sections (using the middle column) and put
labels for each section (stage of the process) in the top row. We add a combo box and Web
180
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
services invoke button in the second cell on the left side, and the repeat in the bottom cell of
the left column. At the end of this section your page should look something like Figure 4-56.
Figure 4-56 How your page will look once the Web service integration is completed
Take the following steps to modify the page to look like Figure 4-56:
1. Import the following images in to the stockControl component:
– One.gif
– Two.gif
– VerticalBar.gif
These images are available for download. Instructions on how to get them are in
Appendix C, “Additional material” on page 279.
2. In the top left cell, add an image control and set the image to be One.gif.
3. Next to that image, add a label and set the value to be Select Supplier and Product.
4. Set the font style to be Tahoma, size to be 10, bold, and red.
5. Add an image to the last cell on the first row and choose Two.gif as the image.
6. Add a label next to the image and set its value to Enter details and save.
7. In the first cell of the second row, add a table and do the following:
a. Remove one row and add two columns so you have a 1x4 table.
b. In the first cell of the table add a button and label it Get Suppliers.
c. In the second cell, type Select Supplier.
d. In the third cell, add a combo box control.
e. In the fourth cell, add a Hidden Input. However you will not find this control on the UI
Controls panel, but you will find a Select Control in the UI Control panel, second from
the top. Select this, and when you drag and drop this onto the page, a window pops up
showing a comprehensive list of all control currently available within Designer for the
active component. In the Other Controls - Web Client section of the list, you will find the
Chapter 4. Customization using Lotus Component Designer
181
Hidden Input control. Select this and a generic tag appears on your page. Although
this is not hidden in the design view, it is not visible on the deployed component.
Having the control visible at design time is necessary so we can select and set its
properties.
8. Now add a repeat control on to the page. You will find this control in the Container
Controls section.
9. Drop a table into the repeat control and set up the table as follows:
Tip: If you find it difficult to select the table or cells within the table, there are two ways
that can help. The outline on the bottom left of Lotus Component Designer is very
useful for finding a specific control and highlighting it. Alternatively, if it is a specific cell
you wish to type into, double-click that cell.
a. We want to set the top border of the table to have a solid red line. With the table
selected you will see that there is no way to set just the top border, which does not
mean that it cannot be done. Just about every control in Lotus Component Designer
can have CSS directly applied to it. Whether that CSS makes sense is down to what
you put in, but you can add any CSS you wish. We want to apply our own custom CSS
to the table, so, in the All Properties tab of the Properties panel, scroll down to the style
property and paste in the following:
border-top: thin solid rgb(185,36,36);width:400px
While still in All properties set the align property to top.
b. In the top row do the following:
•
•
•
•
First cell, type in Make:.
Second cell, drag and drop a Computed Field from the UI Controls.
Third cell, type in Model:.
Fourth cell, drag and drop a Computed Field from the UI Controls.
c. In the second row do the same, this time typing Description: and Unit Price: for the
first and third cells, respectively.
d. In the bottom row, add a button to the last cell and label it Select >>.
We are now finished adding controls and labels to the page and it should look like that in
Figure 4-56 on page 181, but right now, none of these controls do anything. We need to set
the events on some of the controls and bind other controls to the appropriate Web services
data to make them useful.
Adding the Web services adapters to the page
We need both Web service adapters on this page. One returns a list of suppliers for our
combo box, and the other populates the content of our repeat when a supplier is selected
from the list of suppliers.
Not surprisingly, this is done in exactly the same way as adding a schema data source or a
relational query. Select some white space in the page, so we have the page selected and not
a control, and go to the Data tab of the Properties panel. Click the Add button and this time
select Web Services Adapter.
182
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Once the Web service adapter has been added, you will see a Data source: Web Service
section appear on the Data tab, next to the list of data sources with four fields in it. Set the
following for these fields:
򐂰
򐂰
򐂰
򐂰
Web Service: Choose SuppliersServiceSoapBinding_getSupplierNames.
Request Document: Change the value to reqDocSupplierNames.
Response Document: Change the value to reqDocSupplierNames.
Fault Document: Leave this as is, as we will not be handling it.
The Data panel should now look like Figure 4-57, “How the Data panel should appear at this
stage” on page 183.
Figure 4-57 How the Data panel should appear at this stage
Now add the second Web service, getProductsBySupplier, in the same manor as we did
when adding the first Web service adapter, and set the fields as follows:
򐂰
򐂰
򐂰
򐂰
Web Service: Choose SuppliersServiceSoapBinding_getProductsBySupplier.
Request Document: Change the value to reqDocSupplierProducts.
Response Document: Change the value to respDocSupplierProducts.
Fault Document: Again, leave this as is, as we will not be handling it.
The Data panel should now look like Figure 4-58.
Figure 4-58 How the Data panel should appear at this stage
Now that we have the Web services on the page, we have labeled the request documents
and response documents with names that makes sense, so we can see what we are binding
our controls to. Now we need to bind our controls to the Web services so that the data is
displayed.
Chapter 4. Customization using Lotus Component Designer
183
Binding to the Web services
We have a few controls that need to be bound to various parts of the Web services. We start
with the combo box.
There are two things that need to be set on this, the list of supplier names, which we get from
the getSupplierNames adapter, but the value that is currently selected is the value that we
need to bind to the request document for getProductsBySupplier. So this control is unique on
our page, as it actually uses both Web services — one to populate its list, and the second to
indicate which supplier products we want to see. If you select the combo box, you will see on
the list of tabs in the Properties panel that we have a Values tab. This is where we can bind
our list of supplier names returned from the getSupplierNames adapter. We do, however, add
a top of the list item (a dummy value) as a visual clue for the users. So from the Values tab,
click the Add Item button and a single entry appears in the table of values below the button,
showing untitled. Change this to --select supplier-- and give it a value of none. Giving it a
value is important, as all entries are expected to have a value, but what that value is does not
matter. The idea is that when selected, no records show up.
Next we bind to the actual Web services data, so click Add Formula Item and you are
presented with the script editor window again. This time choose XPath as the language, and
respDocSupplierNames as the data source. You will notice a reference list on the left. This
is the default tab that is shown when the editor is opened. Choose the Schema tab and the
data structure is displayed, reflecting your data source choice. The data structure you should
see is that of the getSupplierNames response document. For the combo box the formula item
handles an array or list of items by pointing to the impl:item node of the data structure.
Multiple values will be returned and interpreted as a list. So double-click impl:item and the
correct XPath expression should appear in the edit pane of the Script Editor. At this point, the
window should look like Figure 4-59.
Figure 4-59 The correct XPath expression should appear in the edit pane of the script editor
Click OK and save the page. Now we have set up the means of presenting a list of supplier
names. Next the selected supplier name needs to be bound to the request document for
getProductsBySupplier, which is done by going to the Data tab and binding the combo box to
the request document supplierName field. To do this:
򐂰 Select reqDocSupplierProducts for the data source.
򐂰 Select impl:supplierName for the data binding.
184
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
The selected value of the combo box is used as the parameter for the request document of
getProductsBySupplier. The next thing that needs to be done is getting the repeat control to
iterate over all the documents. This is done by binding the value of the repeat to the root of
the list of products that will be returned, by doing the following:
1. Select the repeat (if it is unclear whether the repeat is selected, use the outline panel as a
guide).
2. Go to the Data tab of the Properties panel.
3. Select respDocSupplierProducts for the data source.
4. Select impl:item[impl:Product] as the data binding (Figure 4-60).
5. Set the collectionName to supplierProduct (in the options section of the same panel).
Figure 4-60 Select impl:item[impl:Product] as the data binding
And that is it. The repeat now iterates over all the products returned in the response
document. So now the computed fields need to be bound to that data so that for each
iteration, they present the correct data. The repeat handles iteration through each product
and makes the data for the current product available for us to reference. So when we are
binding the computed field controls, we use the repeat controls collection name as our
reference. One other thing should be noted. When binding Web services data, the values
need to be relative values, which does not happen by default, so when binding the controls,
bind in the normal way, and then delete everything but the last part of the binding. We go
through the first one in detail to reinforce this concept. We start with the Make computed field,
as follows:
1. Select the computed field control relating to the product Make and go to the Value tab.
2. For the data source choose the collection name you set on the repeat (supplierProduct).
3. From the Data binding drop-down, drill down to the make field and select it.
4. Remove the other nodes from the path (for example, /node1/node1.1/node1.1.1 to
node1.1.1).
Chapter 4. Customization using Lotus Component Designer
185
Figure 4-61 shows the binding of the make computed field. Note that the value in the actual
combo box is what we are looking for (not the full path). So select the make field and then edit
the value of the Data Binding field to just show Impl:make.
Figure 4-61 Binding of the make computed field
Now bind the remaining three fields inside the repeat in exactly the same manor, selecting the
repeat’s collection name as the data source and binding to the correct node of the data
structure, and then editing it to have only the last part of the field.
We have now bound all our data to the various parts of the page. It should all work, correct?
Not quite. We bound our controls, but we need to invoke the Web service in order to get the
data.
Web services vary, and the tools that create them vary, too. In some circumstances, it is
possible to set the Web service to autoExecute from the All Properties panel for the Web
services data. The Web service we deployed does not support this functionality, but we use
JavaScript to invoke the Web service, so this does not affect us. We invoke the Web service
by using the button for getting the suppliers names. The combo box itself is going to invoke
the second Web service when a selection is made, returning all of the products for the given
supplier.
To invoke the getSupplierNames Web service, we need to supply a parameter. We use a
static value, which we set on the hidden input control we added earlier. So, let us set up the
hidden field first.
With the hidden input selected, you should only see one tab in the Properties panel, the All
Properties tab. First bind its value property to the startsWith field of the
reqDocSupplierNames data source. To do this click the value column of the value property,
and you should see a blue diamond appear on the right, as shown in Figure 4-62.
Figure 4-62 Showing field values set and the blue diamond to open the script editor
186
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
When you click the blue diamond, you are presented with two options, Use static value and
computed value. Choose computed value and the script editor appears. In much the same
way as we did when binding the combo box formula item, select the language to be XPath,
and this time, select reqDocSupplierNames as the data source. Then from the Schema tab
on the left, select impl:startsWith and click OK. This now means that whatever is set on the
hidden input is what is used on the request document for getting the supplier names.
But we still have not set a value. To do this, we introduce another common feature of all input
controls, and that is the default value. Default values are very useful where you depend on a
value being present, even if no value was entered. Setting a value here allows us to bind the
actual control to some data source, while still ensuring that even when the user does not
enter a value, a default value will be set. To do this, go to the defaultValue property and type
in an asterisk (*). You should now have a page looking much line the one in Figure 4-63.
Figure 4-63 Preview of how your page should look at this stage
Now that we bound all the controls to the various Web Service data, we need to invoke the
Web service actions so that the data is retrieve from the Web service and made available to
the controls.
Invoking the Web services
As mentioned above, we have two Web services that need to invoked — one to get the
suppliers names, and the other to get the products when a supplier has been selected. To
invoke the Web services we add simple actions to the various controls, using the following
steps:
1. With the Get Suppliers button selected, go to the Events panel and with onclick selected
as the event, select the Simple Actions radio button.
a. Click Add Action.
b. On the Add Simple Action window, select All for the category.
c. Select Invoke Web Service.
Chapter 4. Customization using Lotus Component Designer
187
d. You are then presented with a single drop-down box to Select Web Service name.
Select SuppliersServiceSoapBinding_getSupplierNames.
2. Now for the combo box we do the same, only selecting a different event and a different
Web service. Select the SupplierName combo box and go to the Events.
a. This time, select the onchange event.
b. Select the Simple Actions radio button.
c. Add a simple action, the Invoke Web Service, only this time select the other Web
service SuppliersServiceSoapBinding_getProductsBySupplier.
So now the Web services are invoked. The combo box is populated with the list of suppliers
when the Get Suppliers button is clicked. The repeat and its controls are populated with the
products when a supplier is selected in the combo box. However, there is one more thing that
can be done so simplify the task of adding a new item to the stock control. With the
component as is, the user would have to manually type the details from the list of products
into the corresponding edit box fields in order to add an item to the stock control system.
What we to do now is attach an action to the Select >> button that we added to the repeat
that copies over the corresponding data. This falls outside of the abilities of a simple action,
as we want to copy the values for a specific item in the repeat across to the Items edit boxes,
so we create a JavaScript action to do this job.
Copying field data with a JavaScript action
Attaching a JavaScript action to a control is done in much the same way as a simple action,
the only difference being that we need to write some code. This code, once executed, should
find a specific control, get its value, and set it as the value of another control. The script
should do this for all the values we are interested in. To do this we need a way of finding the
fields. You may have noticed that every single control that has been added so far was given a
name. These names must be unique, and Lotus Component Designer does a very good job
of keeping it this way by incrementing the numeral append to the name of each control. When
writing JavaScript that references different controls, it is always a good idea to rename these
controls with names that make more sense in the script. By default, each edit box is given the
name inputText<number>, which can make understanding the JavaScript that references a
lot of edit boxes hard to understand. So let us rename the computed field and edit box control
names to more meaningful names before trying to reference them in JavaScript.
Let us start with the computed field controls. We detail the steps for renaming the first control,
and the rest should be done using the same steps. It is no harm to keep to a consistent
naming convention to differ controls from each other. So when renaming Computed field
controls, use the following convention: <fieldName>Fld. In the steps below, we name the
make field makeFld. Similarly, when naming the edit box controls, we use the convention of
appending Inp to each control.
Select the computed field for the make value, and on the Computed Field tab of the
Properties panel, change the name from computedField1 to makeFld.
Rename the rest of the Computed field controls in the same manor, using the following
names:
򐂰 Model: modelFld
򐂰 Description: descriptionFld
򐂰 Unit Price: unitPriceFld
We also need to rename the Suppliers combo box in the same manor, so rename it to be
suppliersCmbx.
188
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Now do the very same for the Edit box controls. You will notice that you cannot select one of
the edit boxes from within the page. That is expected since it is in fact considered one control,
our StockItemPanel custom control. To name these, open up the custom control again and
select the controls and rename the controls using the following names:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Supplier: supplierInp
Make: makeInp
Model: modelInp
Quantity: quantityInp
Owner: ownerInp
Description: descriptionInp
Price: priceInp
We are now ready to add our JavaScript, which now makes a little sense when it comes to
referencing all the different controls. There are a few edit box controls that have no
corresponding computed field values, but we can still supply some default values at least to
make the users’ experience a little bit easier, namely the owner. In the JavaScript, we set this
value to be the value of the current user in that is entering the data. We leave the quantity
empty, as we should not assume any value.
Back on the StockEntry page, with the Select >> button selected, to the Events panel, and
with the onclick event selected click the Open Script Dialog button, which can be found on
the top right corner of the JavaScript pane. Figure 4-64 shows this button highlighted with a
red box.
Figure 4-64 Open Script Dialog button, which can be found on the top right corner of the JavaScript pane
Chapter 4. Customization using Lotus Component Designer
189
Click this button to open up the editor. Enter in the following JavaScript (Example 4-1) in order
to copy the data across from the computed fields to the edit boxes.
Example 4-1 JavaScript in order to copy the data across from the computed fields to the edit boxes
getComponent("supplierInp").setValue(
getComponent("supplierCmboBox").getValue());
getComponent("makeInp").setValue(
getComponent("makeFld").getValue());
getComponent("modelInp").setValue(
getComponent("modelFld").getValue());
getComponent("descriptionInp").setValue(
getComponent("descriptionFld").getValue());
getComponent("priceInp").setValue(
getComponent("priceFld").getValue());
getComponent("ownerInp").setValue(
context.getUser().getFullName());
When complete, click OK and the JavaScript pane should now look more like Figure 4-65.
Figure 4-65 Preview of how the JavaScripts pane should look
190
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
And that is it. Deploy the component and try it out. You should be able to click AddStockItem
and see a radically changed page, and click the Get Suppliers button as see the list of
suppliers populated in the combo box. Try selecting one and you should see the list of
products appear on the page. And to wrap it all up, clicking the Select button, you should see
all the selected values appear in the edit boxes. Your deployed component should look
similar to Figure 4-66.
Figure 4-66 Your deployed component should look similar to this
The stock control component is now complete. Of course there are many areas in which this
could be improved, but this should give you a good introduction to how to create a fully
functioning component from within Lotus Component Designer.
Conclusion
In this section we created Web service adapters and used them in existing page. We showed
how Lotus Component Designer can easily handle multiple data sources on the one page,
and how we can use other interesting controls to list out the values returned from the Web
service. We also showed how we can create custom JavaScript actions to extract this
information and use it to supplement the entry being created.
Now we have a stock management system that does it all. The users of this system no longer
need to manually enter much information at all. Our component is not only complete to the
ITSOCOOL requirements, it is a point-and-click component, too. The purchase ordering
system should make use of this information. Since the sales staff can only raise orders for
items that are in stock, the purchase ordering system should tap into this information and
make the stock data more accessible. The next section covers this using a different approach
to using combo boxes and repeats. Instead, we use an Ajax control to help prompt the sales
staff using the stock items available.
4.5 Adding Ajax to the purchase ordering system
As mentioned in the conclusion of the last section, all the stock information is available. If we
can access this information in the stock control center component, why not access it in the
purchase ordering system. Making the stock data available to the purchase order system is
the focus of this section. Using the information already available by the stock control center,
creating a new order in the purchase ordering system can be made much simpler. The
Chapter 4. Customization using Lotus Component Designer
191
approach is to use Ajax controls, specifically the typeahead Ajax functionality that can be
utilized on any edit box. On top of this, we supply additional buttons — one button to update
the rest of the stock-related fields on the order; and to complete the ordering process even
further, we add a second button that takes the value set on the quantity field and updates the
Sale Price field to be based on the quantity multiplied by the unit price.
4.5.1 Introducing Ajax usage within Lotus Component Designer
From within Lotus Component Designer there are two out-of-the-box Ajax possibilities. The
first we briefly discussed already, the typeahead. This control operates on a list of values,
which are typically supplied as a comma-delimited string, but you can actually specify the
delimiter if the comma does not suit (we keep it simple and use the default delimiter).
The second Ajax possibility is using partial refresh. This is where a single control on the page
is refreshed. This could be large container control, such as panel (where all its children would
also be refreshed), or as small as a single edit box.
Adding the Ajax typeahead to the Order Item page
To add this functionality we need to add the relational data source to the page. Creating them
again manually is fine, but it is also possible to select the connection (ITSOCOOL_DB) from
the StockControl component and paste it in the connections section of the PurchaseOrdering
component. You can do the same for the relational query, copying the AllStock relational
query. Once both the connection and the relational query have been created, add the
relational query to the page. Again, this is done by opening the OrderItem page and selecting
white space somewhere on the page (to ensure that the page is selected, not a control on the
page). Then from the Data tab on the Properties panel, click Add and select Relational Data
Source. Give the data source a more meaningful name than jdbc1. Set the name to
allStock. Then select AllStock from the drop-down list for the relational data source.
Now that we have access to the stock data, one additional step needs to be taken to allow all
of the data to be available, and that is to set this specific data source to ignore request
parameters. Failing to do this results in the relational data source being set up for a new
document (record in the case of a relational data source). The request parameters are
queried when a page is being loaded by all of the data sources on a page, and initializing
based on those parameters. We have already seen this when we set the target document
property on a open page simple action. For the relational data source, we want all the data to
be available, and not a new record ready to be written to. This is only an issue because the
page is always be opened to create a new document.
To get the relational query to ignore this create new record instruction, we set a property on
the relational data store to ignore request parameters. To do this, go to the All properties of
page and scroll down to the data section and expand it. Open up the jdbcSdoData section
and you should find the ignoreRequestParameters property. Set this property to true.
192
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
The data source is set up for the page. Now the page needs to be modified slightly to add in
the new functionality. Two new buttons are added to a new column, which is inserted after the
second column. At the end you should have an OrderItem page looking much like the one in
Figure 4-67.
Figure 4-67 Preview of the OrderItem page - yours should look very similar
The way the Ajax typeahead works is that when the user starts typing into the make edit box,
a list of all available makes that match what has been typed in so far is shown. That list
becomes shorter as the user types in a specific make. When a make is selected, the user
then starts typing in the model, and an Ajax typeahead offers a list of matching models based
on the make they choose, and what they have already typed in. When the make and model
have been entered, the user can click the update, and the rest of the fields relating to the
specific stock item are filled in for the user. The user then selects the date the order is due by
and the quantity that was ordered. Then clicking the calc button calculates the sale price
using the unit price and the quantity. The order can then be modified further if needed and
then saved in the usual manor.
Using JavaScript to connect to the relational data store
In order to make use of typeahead we need to supply it with a comma-separated list of
values. To do this we use JavaScript. The typeahead takes its list of values using the
valueList property, so our JavaScript computed value should be set on this property. To do
this select the make edit box, and in the Type ahead tab of the Properties panel, tick the
Enable Type ahead check box, and ensure the Mode is set to Full. This mode is important,
as it defines what parts of the session are available back on the server when getting the list of
values. For us, we want access to everything, so we can access the data source. The other
values, Partial and External, refer to partially restoring the session on the server, whereby it is
more optimal. You are not restoring things you might not need to retrieve your values, so only
the edit box part of the page is restored. The external is used when you have provided your
own external servlet that will return the list of suggestions.
Chapter 4. Customization using Lotus Component Designer
193
In the suggestions box, click the blue diamond and select Compute Value, and when the
script editor window opens, select JavaScript as the language and enter in the code shown
in Example 4-2.
Example 4-2 Compute value code
//fields will hold our comma separated list of values
var suggestions = "";
//first lets get the stock table
var stockTable = allStock.get("STOCK");
//now lets just check that we have the table and they are are rows in it
if (stockTable instanceof java.util.List && stockTable.size() > 0){
//ok, lets iterate over the rows of data available
for (var j = 0; j < stockTable.size(); j++){
var row = stockTable.get(j);
//get the value of the MAKE field
var make = row.get("MAKE");
//Just make sure we don't already have it
if (suggestions.search(make) == -1){
//if not in the list, add it (and a comma too)
suggestions += make + ",";
}
}
}
//return the list of suggestions.
return suggestions;
As you can see from the JavaScript, we simply get the STOCK table rows, iterate through
them getting the MAKE field each time, and add it to the suggestions string if it is not already
on it.
And that is it. Typeahead works now. You can deploy the component again and see it
working. But there is more to be added to the page before it is complete. Next we need to
enable typeahead for the model edit box, too. The only difference is that this time we only add
the values to the suggestions string if the model is one that has the same make value as what
is currently set on the make edit box. Example 4-3 is how the script should look.
Example 4-3 Code to add the values to the suggestions string if the model is one that has the same
make value as what is currently set on the make edit box
//Create the suggestions string variable, on which we will add
//all valid suggestions as a comma separated set of values.
var suggestions = "";
//first lets get the stock table
var stockTable = allStock.get("STOCK");
//now lets just check that we have the table and they are are rows in it
if (stockTable instanceof java.util.List && stockTable.size() > 0){
//first get the makeInp value, as we should only add models
//which have the same make value as what is selected in makeInp
var selectedMake = getComponent("makeInp").getValue();
//ok, lets iterate over the rows of data available
for (var j = 0; j < stockTable.size(); j++){
//get the row at index j
var row = stockTable.get(j);
194
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
//get the MAKE value
var make = row.get("MAKE");
//get the MODEL value
var model = row.get("MODEL");
//check if this the make of this row is the same
//as what is currently set on the make edit box
if (selectedMake == make
&& suggestions.search(model) == -1){
//add the model to to our suggestion string (and
//append with a comma)
suggestions += model + ",";
}
}
}
return fields;
As mentioned above, this script only slightly differs in so far as the list of valid values is
determined by slightly different criteria. Instead of getting a full list of what is available, we
only want models that have the same make value as the make value already selected in the
make edit box. Now that typeahead is complete, what would be good is that with one click of
a button, the rest of the fields could be updated based on the selection, which is what we do
in the next section.
Finishing touches to the Order Item page
So now that the user is able to use typeahead to find the product she wants, the next thing to
do is to add a JavaScript action to the Update>> button, so that when the user has made her
selection, she can click this button and the other edit box controls will be updated according
to the product she selected. This is very similar to what we did in the Web services section
when we added a JavaScript action to the Select>> button to copy the fields across. The key
difference is that we only have the make and model values, so from that we need to iterate
over the records to find the appropriate product. Once we find it, we can get all the values of
interest and set them on the appropriate controls and then quit the iteration. Again, in order to
set the values on the controls we need to be able to find those controls, so let us give them
names that make sense. Name the controls (associated with the following labels) as below:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Customer: customerInp
Make: makeInp
Model: modelInp
Due Date: dueDateInp
Quantity: quantityInp
Order Owner: orderOwnerInp
Stock Item Owner: stockOwnerInp
Order Date: orderDateInp
Unit Price: unitPriceInp
Sale Price: salePricesInp
Chapter 4. Customization using Lotus Component Designer
195
Now that we have a way of finding all the controls in a way that makes the code a little more
readable, it is time to attach the script to the button. The following script (Example 4-4) takes
the values set on the make and model controls and iterates over the available records looking
for the product matching the specified make and model. When the record is found, the
relevant details are read from that record and set on the related controls.
Example 4-4 The following script takes the values set on the make and model controls and iterates
over the available records looking for the product matching the specified make and model
//first lets get the stock table
var stockTable = rdbStockData.get("STOCK");
//now lets just check that we have the table and they are are
//rows in it
if (stockTable instanceof java.util.List && stockTable.size() > 0){
//ok, lets iterate over the rows of data available and find
//the row that matches what is set on the make and model
//edit boxes
var selectedMake = getComponent("makeInp").getValue();
var selectedModel = getComponent("modelInp").getValue();
//iterate over the rows until we find a match
for (var j = 0; j < stockTable.size(); j++){
var row = stockTable.get(j);
var make = row.get("MAKE");
var model = row.get("MODEL");
//check if the make and model match the control values
if (selectedMake == make && selectedModel == model){
//we have found a match, copy the values
//from the record to the controls
getComponent("descriptionInp")
.setValue(row.get("DESCRIPTION"));
//set the order owner to the current user name
getComponent("orderOwnerInp")
.setValue(context.getUser().getFullName());
getComponent("stockOwnerInp")
.setValue(row.get("OWNER"));
getComponent("unitPriceInp")
.setValue(row.get("PRICE"));
//lets set the orderDate to todays date
getComponent("orderDateInp")
.setValue(@Now().toString());
//break out of the iteration, we are finished here
break;
}
}
}
In the script above, the same approach of getting the records is used. But this time, instead of
adding the values found to a string, we iterate until we find the exact record that matches
what is set on the makeInp and modeInp controls. Then we use the getComponent() call to
find the specific control as before, and set the relevant value on it from the record. The last
line break simply causes the iteration to end, as there is no point continuing to iterate once we
have found the correct record and set the values on the controls.
The only task left at this point is to add an action to the Calc>> button that reads the quantity
and unit price, and calculates the sale price based on this. In a production component a more
complex calculation would be used, but the purpose here is not to demonstrate a fancy
196
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
calculation, it is more to show how it can be done. This script simply finds the two controls,
takes their values, and converts them in to integer values that we can use to calculate with.
The result is then set on the sale price control. Example 4-5 is the script that should be added
to the onclick event of the Calc>> button.
Example 4-5 This script simply finds the two controls, takes their values, and converts them into integer
values that we can use to calculate with
//first get the unitPrice controls value, as there is
//no point in continuing if this is not already set.
var unitPrice = getComponent("unitPriceInp").getValue();
//check if a value has been applied to the unitPrice control
if (unitPrice != null && unitPrice != ""){
//convert the string value into an integer value
var unitPriceInt = parseInt(unitPrice);
//get the sale price control (as we will want to apply
//our result
//to this control
var priceInp = getComponent("salePriceInp");
//convert the quantity value to an integer for the calcuation
var quantityValue = getComponent("quantityInp").getValue();
//calcuate the sale price
var salePrice = parseInt(quantityValue) * unitPriceInt;
//for demonstration purposes, here is how to print a
//line to the standardOut.log file
println("The value being set on the Sale Price Control is: "
+ salePrice);
//now set the result of the calculation on the sale
//price control
priceInp.setValue(salePrice);
}
The component is now complete and fully working, with typeahead and some custom actions
that reference a relational data store and set values on controls based on that. We have
reached the end of our task in building two components from the ground up.
But there is one little flaw that we have running throughout both components. In previous
chapters, we customized Portal Express with our own theme. And now the title on all of the
pages in both of our components stands out too much. We should not have a blue title, but a
red one. And we have created all of these pages, only to discover right at the end that we
should change this. Thankfully, we used a custom control as a template in each of our
controls. This means that we can alter the color of the componentTitle in one place and
immediately see the change reflected in every page we created. Try it now. Open the
pageTemplate custom control in the Purchase Orders component and change the
componentTitle font color to red and redeploy. You will immediately see that on all of the
pages the color has changed to red. This is another reason why custom controls really help
when developing components within Lotus Component Designer.
Chapter 4. Customization using Lotus Component Designer
197
4.6 Conclusion
At the start of this chapter it was assumed that creating a component from the ground up was
a new experience. We started at this point, and created a simple but effective component,
showing how to define the data that we want the component to handle, how to create a query
for viewing the list of data stored, and how to create a data entry and edit page to add and
modify data, respectively. We also introduced simple actions and showed how these can
save development time. Before we created any pages, we created a custom control,
introducing the concept of creating our own controls that meet the specific needs of our
component. Further on in the chapter we showed how we could take this custom control and
reference it from other components.
After creating a simple component using the default docDB data store, we created a new
component (the stock control component) that demonstrated the ease in which we can use
data sources other than the built-in docDB data store. We also showed how we can use
JavaScript for actions where no simple action fits the requirement.
We then went on to include Web services in our stock control component, and show how
easy it is to use one data source to assist in the creation of records on another.
Finally, we went back to the purchase order component and enhanced it to reference the
relational data store, and introduced one of the Ajax controls, the typeahead control. We
showed how the typeahead can be used to operate on the relational data source to assist the
user in selecting products based on what is in stock. We went further to enhance the order
entry page by adding buttons that allowed the user to update most fields on the page, based
on the selection he made from the typeahead controls. We finished it by adding another
JavaScript action to calculate the sale price.
Although this chapter is more of an introduction to what can be done in Lotus Component
Designer, we covered some large areas and touched on many aspects of the tool. But this is
by no means the extent of its capabilities — that would be a book in itself. However, the areas
covered here will hopefully enable you to create more complex, larger components without
difficulty.
It is important to remember that there is embedded help that can be found by clicking the
Help menu and selecting Help Contents. There you should see all of the help topics
available from within Lotus Component Designer. The specific sections that reference Lotus
Component Designer can be clearly seen among the others in the help section, as they all
start with Lotus Component Designer.
Even this built-in help is not exhaustive, and on occasion you may find that the specific area
you are trying to learn about, or have stumbled into difficulty with, is not covered, or not
covered enough to satisfy your needs. Articles covering specific functional areas are being
written all the time and made available on the IBM Web site, in the developerWorks® Web
site. It is a good idea to visit the developerWorks Web site from time to time, as it can be a
great site for learning things you did not even know were possible, as well as possibly
answering your specific questions. These resource can be found at:
http://www.ibm.com/developerworks/workplace/products/designer/
Further on in this book we come back to these components and show how to allow interaction
between other portlets and Lotus Component Designer components.
198
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5
Chapter 5.
Customization using WebSphere
Portlet Factory
This chapter discusses an example of how WebSphere Portlet Factory might be used to
further customize WebSphere Portal Express. The chapter builds upon the ITSOCOOL
scenario and describes how ITSOCOOL can use WebSphere Portlet Factory to build a
reporting portlet for the warehouse manager. This portlet displays a chart populated from a
relational data store (DB2 is used in the example, although any relational data store can be
used). Non relational data stores, such as Lotus Domino, can also be used to populate the
charts, although setting this up requires a slightly different process, and is not covered in this
paper. A service provider is also built in WebSphere Portlet Factory, which will act as an
intermediary between the chart and DB2.
To complete the example in this chapter, readers need installed copies of WebSphere Portal
Express and WebSphere Portlet Factory 6.0.1. DB2 (or an equivalent data store) is needed to
populate the chart portlet with data. A data source should be configured in WebSphere Portal
Express to point to a database in DB2 (instructions for setting this up are included in
Appendix B, “Configuring the ITSOCOOL environment” on page 269).
Note: The specific models used within this chapter are available for download from the
IBM Redbooks FTP site. For details on how to download this material, refer to Appendix C,
“Additional material” on page 279.
© Copyright IBM Corp. 2007. All rights reserved.
199
5.1 Overview of custom application to be built in this chapter
In the previous chapter we described how to create a collaborative portal application for
managing stock data and order entries. In this chapter we show how to add value to the
application for managers by providing graphical charts that show live data from the stock
management application. This is very simple with the predefined builders included in
WebSphere Portlet Factory.
By the end of this chapter you will have built, tested, and deployed a WebSphere Portlet
Factory application consisting of a service provider and a service consumer. The service
provider acts as an intermediary between your application and your backend data store, and
provides this functionality as a service to be consumed by other builders or applications. The
service consumer in this case is another model in WebSphere Portlet Factory that contains a
chart populated via the service provided by the service provider. This service consumer
model is converted into a portlet and deployed to WebSphere Portal Express. Building
applications in terms of service providers and consumers is part of what is known as
service-oriented architecture (SOA). Applications that are part of an SOA are generally
loosely coupled, more modular, and ultimately more extensible and adaptive than non SOA
applications. For more information about building applications as part of an SOA, see:
http://www-128.ibm.com/developerworks/cmp/soa/?S_TACT=105AGY33&S_CMP=HIVIS
5.1.1 Value to the developer
In the context of the ITSO scenario, developers will learn how they can easily build, test, and
deploy WebSphere Portlet Factory applications. Developers will learn how to build service
providers and consumers in WebSphere Portlet Factory, and produce charts based on
relational data stores. By the end of this chapter, developers will also know some of the key
differences between Lotus Component Designer and WebSphere Portlet Factory, and what
scenarios require one tool over the other.
5.1.2 Value to the user
The deployed portlet allows the ITSOCOOL warehouse manager to view stock levels for each
model, in an easy-to-read pie chart format. This kind of portlet can easily be modified and
extended to fit a wide variety of scenarios, particularly those centering around use cases for
displaying reports to management.
5.2 Introduction to WebSphere Portlet Factory
WebSphere Portlet Factory is a powerful, easy-to-use development tool for building portlets
and portal applications. Using WebSphere Portlet Factory, developers can automate the
generation of custom portlets without requiring any coding.
WebSphere Portlet Factory was designed for rapid application development (RAD) and has a
large number of built-in wizards to complete various development tasks, such as
communicating with Web services, formatting data, adding graphical charts, and
communicating with various data sources and enterprise applications (including DB2, SQL
Server™, Lotus Domino, and SAP). WebSphere Portlet Factory lets developers automate the
process of building portlets and eliminates the need to code multiple copies of similar portlets.
Developers can simply take one or more of the built-in wizards and combine them into custom
portlets to quickly and easily provide value to their portal solutions.
200
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5.2.1 Key features
The key features are:
򐂰 Multi-page custom portlets without coding. The architecture of WebSphere Portlet
Factory allows you to easily create complex, multi-page portlets for any number of
common business scenarios. Instead of coding portlets from scratch in Java, you can
work with higher-level entities called builders, which have a simple, wizard-like interface.
By putting a few of these builders together, you get an integrated model, which you can
publish to the portal as a portlet.
򐂰 Robust integration capabilities with enterprise applications and data. Prepackaged
integration components contain interfaces to many other applications and data stores,
such as Lotus Domino, SAP, PeopleSoft®, Siebel®, Web Services, relational databases,
or MS Excel®. These connectors are ready to use and provided out of the box with
WebSphere Portlet Factory.
򐂰 Integration with IBM WebSphere Portal. Portlets developed in WebSphere Portlet Factory
can be automatically deployed to WebSphere Portal at the touch of a button, and several
builders are provided out of the box to interact with WebSphere Portal capabilities
including people awareness, credentials, and the WebSphere Property Broker.
򐂰 Support for SOA development. WebSphere Portlet Factory comes with a set of predefined
builders that developers can use to build service-oriented applications. Using the default
builders, developers do not need to have a deep knowledge of the underlying architecture
to build SOA portlets with WebSphere Portlet Factory.
򐂰 Many portlet variations from a single code base. With WebSphere Portlet Factory’s
profiling capability, you can dynamically generate multiple parameter-based portlets from
a single code base, without the need to change any of the code directly.
򐂰 Automation of frequently occurring development tasks. Code reusability is a strong feature
of WebSphere Portlet Factory. Builders, the basic building blocks of WebSphere Portlet
Factory, can capture your business logic and easily be reused in other portlets or
applications. Developers can create their own builders, or make use of over 150 builders
that come prepackaged with WebSphere Portlet Factory.
򐂰 Standards based development. Although you can build portlets in WebSphere Portlet
Factory without actually writing any code, the full power of the underlying J2EE framework
is available should you choose to use it. WebSphere Portlet Factory applications are built
using a variety of common development standards, such as XML, HTML, CSS,
JavaScript, Java, and JSP.
5.2.2 Main concepts: builders, models, and profiles
The basic building blocks of applications designed in WebSphere Portlet Factory are
builders. Builders are pluggable modules with easy-to-use, wizard-like user interfaces.
Developers specify builder parameters at design time, which are used by WebSphere Portlet
Factory to dynamically generate your application. For example, you might use a builder to
display a list of data from a backend data store, and specify parameters that populate the list
with data from a DB2 database. Builders are used to do all the hard work behind the scenes,
such as supplying data connections, rendering HTML pages, and executing business logic.
Calls to builders are embedded into models, which can be published to portal servers as
portlets. Builder calls in models can and usually do cooperate with each other to form an
intelligent, complex application. WebSphere Portlet Factory automatically creates all the
necessary HTML, Java, JSP, and XML documents for your application based on the builder
calls in your models.
Chapter 5. Customization using WebSphere Portlet Factory
201
As mentioned earlier, one of the main advantages of WebSphere Portlet Factory is the ability
to create multiple instances of an application from the same code base, but with a different
appearance or behavior. This can be done without directly modifying any code, and without
deploying multiple copies of an application. To achieve this, WebSphere Portlet Factory uses
a mechanism called profiling. Profiles are user-defined sets of parameters that can affect the
behavior of the application. Profiles also support runtime configuration, which means that it is
possible for users to change them from a Web browser.
5.2.3 Versions
In this paper we use WebSphere Portlet Factory 6.0.1.1. The WebSphere Portlet Factory
Designer can be installed into any Eclipse-based environment (including Rational Software
Architect, Rational Application Developer, and Eclipse itself). In this paper we install the
WebSphere Portlet Factory Designer into Eclipse 3.2.1, which comes bundled with
WebSphere Portlet Factory 6.0.1.1.
5.3 The difference between Lotus Component Designer and
WebSphere Portlet Factory
Lotus Component Designer and WebSphere Portlet Factory are both powerful tools used to
develop portlets and composite portal applications, but they differ in the way you work with
them. Within this publication, we provide an opportunity to work with both tools.
Lotus Component Designer is a visual development tool perfectly suited to script developers
familiar with tools such as Lotus Domino or Microsoft Visual Basic, and is used to develop
document-based, collaborative applications. Lotus Component Designer is useful for building
composite applications that include a document store, such as expense report or project
management applications. If you are a Lotus Domino developer, the way Lotus Component
Designer looks and behaves will seem very familiar to you. Lotus Component Designer works
with fields, views, and schemas, and uses both relational data sources (such as DB2) and
non relational data stores (such as Lotus Domino). It is a flexible tool for quickly building
applications consisting of forms and views, and is also a powerful way to combine data from
multiple data sources. Additionally, if you are a Web developer or designer you can quickly
become familiar with Lotus Component Designer, since it is based on HTML, JavaScript, and
XML.
WebSphere Portlet Factory is an Eclipse-based tool perfectly suited for integrating data from
different backend sources (including SAP, Lotus Domino, and Oracle), and building
configurable, role-based composite portlet applications. WebSphere Portlet Factory provides
a large number of unique features out of the box, which can be implemented without writing
any code. Developers who are more used to the Eclipse environment, are comfortable
building applications with wizards, or who want access to the Java API will likely find
WebSphere Portlet Factory to be a useful development tool. With WebSphere Portlet Factory,
developers can rapidly build SOA applications via wizard-like builders, while simultaneously
having the full power of Java at their fingertips. Developers can create their own builders to
promote component reuse, or make use of over 150 builders that come prepackaged with
WebSphere Portlet Factory. Domino developers can also make use of WebSphere Portlet
Factory, as there are a variety of out-of-the-box builders provided for accessing,
manipulating, and formatting Domino data (WebSphere Portlet Factory also provides access
to the Domino Java API).
Both tools are useful in different scenarios, but for many cases your choice of tool will come
down to personal preference. Portlets built in WebSphere Portlet Factory and Lotus
202
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Component Designer are fully JSR-168 compliant, and are even capable of communicating
with each other. Inter-portlet communication between WebSphere Portlet Factory and Lotus
Component Designer portlets is discussed in Chapter 6, “Inter-portlet communication” on
page 221.
5.4 Creating a project in WebSphere Portlet Factory
The first step in building your chart portlet is to create a new project in WebSphere Portlet
Factory. Projects are used in WebSphere Portlet Factory as containers for all of your design
elements (including models, builders, and profiles, as well as Web artifacts such as HTML,
JSP, and XML). For simplicity’s sake, the project we create in this chapter houses both your
service provider and service consumer, although there are many other scenarios where you
would want to split these elements into two separate projects. Splitting your provider and
consumer into separate projects makes your code more modular, and if you are using more
than one consumer it makes sense to build the provider as a standalone project. To keep
things simple, we put both the service provider and consumer into the same project in this
example.
To create a new project for your service provider and consumer:
1. Open the WebSphere Portlet Factory Designer and click the
a Wizard dialog.
button to open the Select
2. Select WebSphere Portlet Factory Project under the WebSphere Portlet Factory folder
and click the Next button.
3. Type stockReports for the project name, and click Next.
Chapter 5. Customization using WebSphere Portlet Factory
203
4. The next window in the wizard allows you to specify feature sets to add to your project.
Your service provider does not need any feature sets, but your service consumer needs a
feature set that provides a builder for generating charts. Select the GreenPoint Web
Chart Builder from the Charting folder, as shown in Figure 5-1, and click Next.
Figure 5-1 Specify feature sets to add to your project
5. Click Next on the Java Settings window.
6. The next window allows you to set up a deployment configuration. You can specify two
deployment configurations here: one for an application server and one for a portal server.
The application server is used for previewing applications from the Designer, and must be
installed locally (it is not possible to specify a remote application server). Applications
previewed in this way are run as Web applications rather than as portlets, and do not have
access to functionality available in the portlet container (such as the WebSphere Property
Broker). To access functionality in the portlet container you need to deploy your
application to a portal server, which is the other server you can set up in this section. If you
have access to both types of servers we advise that you set up a deployment profile for
each one.
Note: You can use the WebSphere_Portal server instance that comes with WebSphere
Portal Express as both your application server and your portal server, although this
requires having WebSphere Portal Express installed on your local machine.
Alternatively, you can use server1 as your application server, which also comes with
WebSphere Portal Express. A good configuration is to run a local application server
(such as server1) for previewing your applications, and then deploy your portlets to a
remote portal server for testing inside a portlet container.
To set up your application server, click the Add button for the Application Server
Deployment Configuration. On the dialog that follows, give your configuration a name and
204
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
description. The exact settings you enter in this window differ depending on your
environment. In this section we use the server1 local application server instance that
comes packaged with WebSphere Portal Express (our settings are shown in Figure 5-2).
Note that if you are using the WebSphere_Portal server instance, you could use the same
settings as what we have used, and would only need to change the WAS Server for the
deployment box (the installed applications dir box will be the same for both server1 and
WebSphere_Portal). Make sure that the installed applications dir field matches a valid
directory in your file system.
Figure 5-2 Local deployment settings - in our case, we use the server1 local application server
instance that comes packaged with WebSphere Portal Express
If you are unsure of your settings, you can click the Test Server Connection button at the
bottom of the dialog. The server connection test is also performed when you click the OK
button. Click OK when you have finished configuring your application server profile.
Chapter 5. Customization using WebSphere Portlet Factory
205
7. The next step is to set up your portal server deployment profile. We use a remote copy of
WebSphere Portal Express, which we mapped to the D drive on our local machine (our
settings are shown in Figure 5-3).
Figure 5-3 Set up your portal server deployment profile
Click the Test Server Connection button if you are unsure of your server settings. Click
OK when finished.
8. When you have finished setting up your deployment profiles, click Finish to complete the
project creation process. A dialog appears asking whether you want to add JAR files for
the feature set. Click Yes to add the feature set JAR files to the Java build path. Another
dialog appears asking whether you would like to deploy your project. Select Yes to deploy
your project to the servers specified in the wizard (this may take several minutes).
Note: When you create a new project in the Designer, you may get a prompt to switch to
the WebSphere Portlet Factory perspective. Perspectives are used to determine particular
combinations of windows (known as views) in Eclipse-based IDEs. Switching to the
WebSphere Portlet Factory perspective displays the most commonly used views for
WebSphere Portlet Factory, and makes it easier for you to follow through with the example
in this chapter.
You should now have a new project in WebSphere Portlet Factory Designer called
stockReports. The next section describes how to add a model to this project to act as your
service provider.
5.5 Building a service provider to a relational data store
Before you can build a portlet that displays a chart, you = need to create a service provider
that provides data for the chart. In this paper we look at creating a service provider to access
a backend DB2 data store, although any relational data store could be used. It is also
possible to link your service provider to a non relational data store such as Domino, although
this is not covered in this paper.
206
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
In this chapter we use the DB2 data store that you used in the previous chapter. If you do not
have a working data store as a result of following through the last chapter, you need to follow
the instructions in Appendix C, “Additional material” on page 279, to set this up. If you choose
to use your own relational data store, note that some of the parameters specified in this
section need to be modified to fit your environment.
Once you have a working relational data store, you need to add a service provider model to
your project. To do this:
1. Click the
button on the Designer toolbar to open the Select a Wizard dialog.
2. Select WebSphere Portlet Factory Model under the WebSphere Portlet Factory folder
and click the Next button.
3. Select the stockReports project and click Next.
4. The next window allows you to pick the type of model you would like to create. Select
Database Service Provider from under the Service Providers heading (see Figure 5-4),
and click the Next button.
Figure 5-4 Pick the type of model you would like to create
5. Enter a name for your provider and click Next. We used stockService in the example.
Chapter 5. Customization using WebSphere Portlet Factory
207
6. The next window allows you to specify your service operations. Operations are commands
that you would like to make available through your service provider. In the example we
only create one operation, which retrieves a list of data from DB2. If you are using the DB2
database created in the previous chapter, you should use the settings shown in
Figure 5-5.
Figure 5-5 Settings for retrieving data from DB2
The SQL DataSource field is populated automatically from the data sources that you have
registered with your local application server, so you should not have to type in the data
source manually. If you have configured your data sources correctly, you should see the
jdbc/ITSOCOOL entry appear in the list (see Appendix B, “Configuring the ITSOCOOL
environment” on page 269, if you have not yet set up the ITSOCOOL data source).
The SQL statement specified in the SQL Statement field returns a list of stock information
(make, model, quantity, owner, and description) from the STOCK table in the ITSOCOOL
DB2 database.
Click Next when you are ready to proceed to the next stage.
Tip: You may get an error when loading the SQL Statement window in the wizard. If
you are getting errors at this stage, make sure that your local application server is
running, and that you have configured your application server deployment profile
correctly.
7. The next step is to configure the service operation. Type getStock for the service
operation name. You can leave the other settings on this window with their defaults. Click
the Next button when you have entered an operation name.
8. Give your model a name (we used stockService in the example) and click Finish.
Once the wizard has finished, you have a new model in your project called stockService. This
model provides your portlet with access to the STOCK table in the ITSOCOOL database in
208
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
DB2. The getStockData model has a built-in interface that allows you to preview the service,
which is covered in the next section.
5.6 Previewing your service provider
At this point you should have a service provider model that accesses a DB2 data store. This
model contains an interface you can use to preview and test the operations in your service.
Previewing your applications in WebSphere Portlet Factory Designer involves setting up a
run profile. Once you have done this you can just click the
icon in the Designer toolbar to
preview your application again. Previewing your applications is an easy way to test your work
from the Designer, and it is often quicker than testing on a portal server.
Tip: You can modify your deployment profiles at any time by right-clicking your project in
Designer and selecting Properties. In the project properties dialog that follows, select
WebSphere Portlet Factory → Deployment Info.
If you have set up your application server deployment profile correctly, you can follow through
these steps to test your application:
1. Open the stockService model in Designer.
2. Select Run → Run from the Menu bar to open the Run Profile dialog.
3. Double-click the WebSphere Portlet Factory Model item (shown in Figure 5-6). A new
configuration will be created underneath the WebSphere Portlet Factory Model heading.
Figure 5-6 WebSphere Portlet Factory Model item
Chapter 5. Customization using WebSphere Portlet Factory
209
4. Give the configuration a more meaningful name (we used WebSphere Portlet Factory Run
Configuration in the example) and click the Run button. This completes the creation of
your run profile. Run the model you currently have open in the Designer. The model is run
on the local application server you set up in your deployment profile in 5.4, “Creating a
project in WebSphere Portlet Factory” on page 203.
Once your application has opened in a browser, you should see the page shown in
Figure 5-7.
Figure 5-7 Once your application has opened in a browser, you should see this page
5. This page displays a list of the operations provided by your service. You can click the
operation name getStock to test the service operation. Depending on the data in your
STOCK database, clicking the getStock link should return something similar to the output
shown in Figure 5-8.
Figure 5-8 Clicking the getStock link should return something similar to the output shown here
Tip: If you are not able to retrieve a stock list as shown in Figure 5-8, check that you do
not have any errors listed in the Problems view in Designer before you test your
application. Common problems include failures to authenticate with your data source
and problems with your deployment profiles. Make sure that you test your deployment
profile for your application server before trying to preview your application (you can test
your deployment profile from the project configuration page), and test your data
sources if you are having authentication problems (you can do this from the
WebSphere administration console).
If you need additional information about working with a deployment profile, refer to the
Portal Express Information Center at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.exp.doc/wpf/welcome.html
Now that you have successfully set up your run profile, you can test your application at
any time by opening the model you want to test and clicking the
button on the
Designer toolbar. Note that this button selects the last run profile that you used, so if the
last run profile you used is not the one that you currently want to select, then you should
click Run → Run from the Menu bar, and then select the run profile that you would like to
use.
210
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5.7 Building a portlet that displays a chart
The final step in building your WebSphere Portlet Factory application is to add a service
consumer model to your project. This model is published to WebSphere Portal Express as a
portlet, and is therefore accessible to users (your service provider model will not be
accessible to users).
Your service consumer model displays a chart that will be populated from data retrieved by
the stockService service provider. To build the service consumer model:
1. Click the
button on the Designer toolbar to open the Select a Wizard dialog.
2. Select WebSphere Portlet Factory Model under the WebSphere Portlet Factory folder
and click the Next button.
3. Select the stockReports project and click Next.
4. The next window allows you to pick the type of model you would like to create. Select List
and Detail Service Consumer from under the Service Consumers heading (see
Figure 5-9), and click the Next button.
Figure 5-9 Select List and Detail Service Consumer from under the Service Consumers as the type
of model
5. Enter a name for your consumer model (we use stockChart). Click the ellipsis button next
to the Provider Model field to open the Choose Model dialog, and then select the
stockService model. Click OK to close the Choose Model dialog, and then click Next to
go to the next window in the WebSphere Portlet Factory Model wizard.
6. This window allows you to specify an operation to retrieve a list of data. Select getStock
from the drop-down list and click Next.
7. The next window allows you to specify settings for how you retrieve data from the backend
data store. The options on this page apply to lists of data retrieved from the service
provider, and allow you to do things such as convert certain fields into links that open
Chapter 5. Customization using WebSphere Portlet Factory
211
details for a particular row, or specify alternate operations to consume when displaying
detail data. Uncheck the Create link to details box and click Next.
8. Give your model a name (we use displayStockChart) and click Finish.
9. When your model has been created, open the Portlet Adapter builder and change the
Portlet Title to Stock Chart (this is the title of the portlet as it appears in WebSphere Portal
Express).
You now have a model that consumes the service provided by the stockService service
provider. You can test the application at this point by clicking the
button on the Designer
toolbar. Depending on the data in your stock data store, you should see a page similar to that
shown in Figure 5-10.
Figure 5-10 Depending on the data in your stock data store, you should see a page similar to this
Once you have created your service consumer, you need to add a Web Charts builder to your
consumer model so that it displays the backend data in a chart rather than a list. To add this
builder and configure it for use in your project:
1. Click the cog button on the Outline view (as shown in Figure 5-11) to open the builder
palette.
Figure 5-11 Click the cog button on the Outline view
212
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. Select Web Charts from the Builder Palette, as shown in Figure 5-12, and click OK to add
a Web Charts builder to your model. The Web Charts builder will load in the main editor
window.
Figure 5-12 Builder palette
3. Give your Web Charts builder a name (we use stockChart in the example).
4. Change the page field to stockChartView_ViewPage. This tells the Web Charts builder
that it should display the chart on the View page of the stockChart model, which loads by
default.
5. For the tag field, specify data. This tells the Web Charts builder to place the chart on the
data tag, which displays the chart in place of the data table displayed previously.
At this point, your settings should be the same as those shown in Figure 5-13.
Figure 5-13 Settings for creating the Web chart
6. For the Chart Type field, specify Pie.
7. Check the box for Provide Custom Style. This allows us to define a custom style for our
chart. You can use one of the default styles if you prefer, but specifying a custom style
gives you more fine-grained control over how your chart appears. Custom styles are
stored in XML files, and can either be generated automatically from the Greenpoint
WebCharts 3D tool (available for download from
Chapter 5. Customization using WebSphere Portlet Factory
213
http://www.gpoint.com/website/WebCharts50/download/download.jsp) or edited
manually in a text editor. The Greenpoint WebCharts 3D tool allows you to edit and
preview your chart styles in a graphical user interface, which you can then export to XML.
To use the same style as the one we are using in the example, copy and paste the
following XML from (Example 5-1) into a file called customPie.xml.
Example 5-1 Copy and paste the following XML from this example into a file called customPie.xml
<?xml version="1.0" encoding="UTF-8"?>
<pieChart depth="Thick" style="Sliced" angle="314" is3D="true">
<axis>
<labelFormat style="Currency" pattern="#,##0.###"/>
<parseFormat pattern="#,##0.###"/>
</axis>
<legend spacing="0" placement="Right" font="Verdana-10">
<decoration style="Simple"/>
</legend>
<elements drawOutline="false" drawShadow="true">
<morph morph="Grow" stage="Cols"/>
</elements>
<title font="Verdana-14-bold">
<decoration style="None"/>
</title>
<paint palette="Modern" paint="Plain"/>
</pieChart>
Tip: Spend some time experimenting with the different chart styles in the Web Charts
builder, or create your own using the Greenpoint WebCharts 3D tool. Note that
changing the chart style might require corresponding changes to the Data
Transformation section of the Web Charts builder, to accommodate changes in the way
data is structured in the chart.
8. Copy the customPie.xml file into the WebContent directory of the stockReports project.
You can copy it into a sub directory under WebContent if you prefer.
9. In the Style Data section of your Web Charts builder, specify the location of the
customPie.xml file using the ellipsis button next to the Style Data field. This tells the
builder to use the custom style you added earlier.
10.In the Chart Data field, type ${DataServices/stockChart/getStock/results/RowSet}. The
settings in the Chart Style and Data section of your Web Charts builder should appear as
shown in Figure 5-14.
Figure 5-14 Defining chart style and data
214
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
11.Fill out the Data Transformation section of the Web Charts builder, as shown in
Figure 5-15. This specifies that you want to see quantity information for each model type in
the stock database.
Figure 5-15 Data Transformation section of the Web Charts builder
12.Save your changes.
You now have a model that displays a chart based on data from a backend DB2 data store.
At this point you should preview your application from Designer to make sure that you have
followed the steps up to this point correctly (you can preview your application by clicking the
button on the Designer toolbar). You should see a page similar to that shown in
Figure 5-16.
Figure 5-16 As you preview this, you should see a page similar to that shown here
Once you are able to successfully preview your application on your application server, you
should proceed to the next section, which describes how to deploy your chart portlet to
WebSphere Portal Express.
Note: When you view charts built using the Web Charts builder, you will notice that by
default an evaluation version message appears at the base of the chart. To remove this
message you need to license your copy of Web Charts. Once you obtain a license code
from Greepoint, you need to enter this code into the webcharts3D.xml file inside the
wc50.jar file. For more information about obtaining a license and configuring your Web
Charts builders contact Greenpoint at info@gpoint.com.
Chapter 5. Customization using WebSphere Portlet Factory
215
5.8 Deploying your chart portlet
For the ITSOCOOL scenario we deploy the chart portlet as part of both the stock and orders
composite applications in WebSphere Portal Express. To do this, right-click the
stockReports project root folder, as shown in Figure 5-17, and select Refresh Portlet
Factory WAR → Refresh Portlet Deployment WAR(s).
Figure 5-17 Right-click the stockReports project root folder - select Refresh Portlet Factory WAR →
Refresh Portlet Deployment WAR(s)
This automatically deploys your portlet to the WebSphere Portal Express installation specified
in your portal server deployment profile.
The next step is to add your portlet to a page in the portal. For the ITSOCOOL scenario, we
add the chart portlet to both the Inventory page and the Orders page. To do this:
1. Log in to the portal as an administrator.
2. Navigate to the Orders page.
3. Click the portlets link to open the Portlet Palette.
4. In the Portlet Palette, type Stock Chart and click Search. When the stock chart appears
(see Figure 5-18), drag and drop it onto the Orders page underneath the discussion
portlet (or above the discussion portlet if your resolution is not high enough to display the
bottom of the discussion portlet).
Figure 5-18 In the Portlet Palette, type Stock Chart and click search
5. Click the portlets link to close the Portlet Palette.
This adds the stock chart to the Orders page, but the page is difficult to view due to the size of
the portlets. To change this, you can put the discussion portlet and the stock chart portlet on
the same row. To do this:
1. Open the page layout settings for the Orders page by clicking the arrow icon in the top
right-hand corner of the Orders tab.
216
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. On the Edit Layout window select the T Layout, as shown in Figure 5-19.
Figure 5-19 Select the T Layout as shown here
3. Using the direction arrows on each portlet, reposition the portlets on the page so that the
stock portlet is on the top row, and the discussion and stock chart portlets are on the
bottom row (Figure 5-20).
Figure 5-20 Positioning the portlets
Chapter 5. Customization using WebSphere Portlet Factory
217
Once the browser reloads, you should see a page that looks similar to that shown in
Figure 5-21.
Figure 5-21 Preview of how the stock chart portlet should appear
The next step is to add the stock chart portlet to the Inventory page. To do this:
1. Navigate to the Inventory page.
2. Click the portlets link to open the Portlet Palette.
3. In the Portlet Palette, type Stock Chart and click the search icon. When the stock chart
appears, as shown in Figure 5-22, drag and drop it onto the Inventory page underneath
the stock portlet.
Figure 5-22 In the Portlet Palette, type Stock Chart and click search
4. Click the portlets link to close the Portlet Palette.
218
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
This adds the stock chart to the Inventory page. Once the browser reloads, you should see a
page that looks similar to that shown in Figure 5-23.
Figure 5-23 Preview of how the Stock Chart Portlet should appear in the Stock Management Center
Tip: If you cannot find your stock chart portlet in the Portlet Palette, make sure that you
have edited the Portlet Title field in the Portlet Adapter builder and then redeploy your
application.
5.9 Conclusion
In this chapter we discussed how developers can leverage the power of WebSphere Portlet
Factory to further customize WebSphere Portal Express. In the context of the ITSOCOOL
scenario, we saw how to add a chart portlet to a portal, which accesses data from a backend
relational data store. We also saw how to preview and deploy Portlet Factory applications to a
portal server, as well as position these portlets on pages in the portal.
If you have followed through the steps in this chapter, you should have a stock chart portlet
that accesses the same ITSOCOOL data store that the Lotus Component Designer stock
portlet accesses. This portlet is a part of both the Inventory page and the Orders page.
In the next chapter, we develop a communication link between the stock chart and the
purchase orders portlet created in 4.3, “Building the purchase ordering component” on
page 133, so that a list of orders is shown for a model clicked in the chart.
Chapter 5. Customization using WebSphere Portlet Factory
219
220
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
6
Chapter 6.
Inter-portlet communication
In this chapter we demonstrate how ITSOCOOL can set up communication between portlets
in WebSphere Portal Express. The stock portlet (built with Lotus Component Designer in
Chapter 4, “Customization using Lotus Component Designer” on page 129) and the chart
portlet (built with WebSphere Portlet Factory in Chapter 5, “Customization using WebSphere
Portlet Factory” on page 199) are used to illustrate how this can be done.
There are a number of ways to facilitate inter-portlet communication in a portal. In
WebSphere Portal Express this is usually done with the WebSphere Property Broker, which
provides interaction between standards-based portlets such as the JSR-168 compliant
portlets built in the previous two chapters. The WebSphere Property Broker comes packaged
with WebSphere Portal Express and allows you to wire portlets together in an easy-to-use,
graphical interface. Wires establish communication lines between portlets based on source
and target properties, which are declared by the developer but configured by users. We use
the WebSphere Property Broker in this chapter to configure the wire between the orders
portlet and the chart portlet.
To complete the example in this chapter, readers need installed copies of WebSphere Portal
Express, WebSphere Portlet Factory 6.0.1, and Lotus Component Designer 6.0. DB2 (or an
equivalent data store will be needed to populate the chart portlet with data). Readers also
need to have built and deployed the orders portlet described in Chapter 4, “Customization
using Lotus Component Designer” on page 129, and the chart portlet described in Chapter 5,
“Customization using WebSphere Portlet Factory” on page 199.
Note: Specific files and resources used within this chapter are available for download from
the IBM Redbooks FTP site. For details on how to download this material, refer to
Appendix C, “Additional material” on page 279.
© Copyright IBM Corp. 2007. All rights reserved.
221
6.1 Overview of custom application to be built in this chapter
Previously, we discussed how to develop an orders portlet using Lotus Component Designer,
a chart portlet using WebSphere Portlet Factory, and how to deploy both of these portlets to
WebSphere Portal Express. In this chapter, we describe how to establish a communication
link (known as a wire) between these two portlets for the ITSOCOOL scenario.
The communication between the two ITSOCOOL portlets will be built around the MODEL
property. A warehouse manager at ITSOCOOL will be able to click a particular model in the
chart portlet (the source portlet) and display orders for this part in the orders portlet (the target
portlet).
In order to achieve this communication, a drill-down event will be added to the chart model in
WebSphere Portlet Factory. When users drill down into the chart (by clicking a model in the
chart), the chart portlet will publish the name of the model as a property to the WebSphere
Property Broker. The WebSphere Property Broker can then farm off this property to any other
portlets that need access to the model selected by the user. The orders portlet will then be
configured to read a model property passed to it from the property broker, and display details
on this model from DB2. Finally, the WebSphere Property Broker will be configured via the
WebSphere Portal Express administration interface to bind the two portlets together (this final
step is needed so that the orders portlet will know that its model property maps to the model
property published by the orders portlet).
By the end of this chapter you will have built and deployed two portlets, one using Lotus
Component Designer and the other using WebSphere Portlet Factory. You will also learn how
to configure these portlets to publish and read property values via the WebSphere Property
Broker.
Note: In Version 6.0.1.1 of WebSphere Portlet Factory, it is only possible to set up a wire
that sends information from a WebSphere Portlet Factory portlet to a Lotus Component
Designer portlet (this is not possible in reverse). This is due to the way WebSphere Portlet
Factory portlets process multi-part MIME requests. This issue has been addressed by the
development team, with the fix contained in the next version of Portlet Factory to be
released.
6.1.1 Value to the developer
By the end of this chapter developers will know how to read properties in Lotus Component
Designer that have been published through the WebSphere Property Broker, and execute
actions to react to changes in these properties. Developers will also learn how to use the
cooperative target builder and event model in WebSphere Portlet Factory, and how to
configure the WebSphere Property broker to facilitate inter-portlet communication between
portlets in WebSphere Portal Express.
Using inter-portlet communication enables portlets developed using different tools to be used
together in composite applications. It encourages reuse of components, and allows
developers to build customizable portlet applications that can be plugged into other portlet
applications via the WebSphere Property Broker.
6.1.2 Value to the user
Inter-communicating portlets add value for users by adding functionality and customizability.
Two portlets can send data between each other to facilitate user actions that were not
222
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
possible without inter-portlet communication, and these portlets can then be moved, edited,
and removed by users without breaking the rest of the application. In the present example,
users can choose to use the orders portlet without the chart portlet if they choose, or vice
versa, but the option is available to them to be able to drill down on the chart portlet to open
relevant information in the orders portlet. Users are able to move the portlets around on the
page (or add them to other pages) as they see fit.
6.2 Building communication into your portlets
This section discusses how to establish communication between the portlets built with
WebSphere Portlet Factory and the portlets built using Lotus Component Designer.
6.2.1 Setting up the chart portlet as a co-operative source portlet
WebSphere Portlet Factory handles communication between portlets by taking an event
triggered in the portal (such as the MODEL property being modified) and then handling this
event by executing an action. The action can be anything from a builder call, to JavaScript, to
Java. While there are other ways to handle events without using WebSphere Property Broker,
using the property broker offers several advantages, such as promoting reuse and loosely
coupling your portlets.
In order to use the property broker to wire the model property from the chart portlet to the
orders portlet, you need to configure the chart portlet to send changes in the model property
to the WebSphere Property Broker. In the next section we demonstrate how to configure the
purchase orders portlet you created in 4.3, “Building the purchase ordering component” on
page 133, to react to these events.
To configure your chart portlets:
1. Open the stockChart model in WebSphere Portlet Factory.
Chapter 6. Inter-portlet communication
223
2. Click the cog icon in the Outline view to open the Builder Palette (see Figure 6-1) and add
a Cooperative Portlet Source builder to your model, as shown in Figure 6-2. Click OK
when finished.
Figure 6-1 Cog icon in the Outline view
Figure 6-2 Add a Cooperative Portlet Source builder to your model
3. When the Cooperative Portlet Source builder loads, give it an appropriate name (we used
publishModelName in the example).
4. Complete the Cooperative Portlet Source builder, as shown in Figure 6-3. This creates an
action that publishes the model property to the property broker. Make sure that you
change the namespace property from the default, as this is used to communicate with the
orders portlet. Leave the Value field blank. This is so that whatever argument you pass in
to the property broker action for the model property will be used as the value of the model
property.
Figure 6-3 Complete the Cooperative Portlet Source builder as shown here
224
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
5. The next step is to configure the Web Charts builder so that it triggers the
publishModelName action when a user clicks a model quantity in the chart. To do this,
open the Web Charts builder and expand the Chart Click Action section. Click the ellipsis
button next to the Method to call field, and select the property broken action you created in
the previous step (as shown in Figure 6-4). Click OK when finished.
Figure 6-4 Select the property broken action you created in the previous step
6. The other settings in the Chart Click Action section of your Web Charts builder should
appear as shown in Figure 6-5. Make that sure you change the Evaluate arguments field
to As the page is rendered, otherwise you will not be publishing the correct properties.
Figure 6-5 The other settings in the Chart Click Action section of your Web Charts builder should
appear as shown here
The ACTION_NAME property is used to send to the property broker. The
${ChartValues/colLabel} value holds the model code corresponding with the pie segment
clicked by the user, and is passed to the pbAction_publishModelName method as the
value of the model property. This property will then be published to the property broker as
model.
7. Save your changes.
Chapter 6. Inter-portlet communication
225
8. To deploy your chart portlet to WebSphere Portal Express, right-click the stockReports
project root folder (see Figure 6-6) and select Refresh Portlet Factory WAR → Refresh
Portlet Deployment WAR(s).
Figure 6-6 Right-click the stockReports project root folder and select Refresh Portlet Factory WAR →
Refresh Portlet Deployment WAR(s)
You have now successfully added support for the WebSphere Property Broker to your chart
portlet.
Now that you have configured your chart portlet to surface the MODEL property, you need to
set up your stock portlet to receive this property.
6.2.2 Setting up the stock portlet as a co-operative target portlet
In this section we configure the orders portlet created in Chapter 4, “Customization using
Lotus Component Designer” on page 129, to read a model property from WebSphere
Property Broker. The orders portlet then reacts to this property change and executes an that
displays a list of orders for the selected model.
To configure your orders portlet, perform these steps:
1. Open the Composite Application → Wiring Properties in your component.
Figure 6-7 Open the Composite Application → Wiring Properties
226
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. In Property Details, fill in the following information and click the Add button. Then save
and close Wiring Properties.
– Name: Model
– Type: String
Figure 6-8 Wiring properties details
3. Open Composite Application → Actions in your component.
Figure 6-9 Open Composite Application → Actions in your component
4. Click New Action in the top. Fill in the New Component Action dialog as follows. Then
click OK.
– Name: processAction
– Component: <your component>
Figure 6-10 Defining the new component action
5. This action saves the value received from the property broker. Set the focus to the canvas
by clicking somewhere inside of the area of the code editor. Then in the Properties tab,
switch to Parameters. Click the Add button to add a new input parameter, set its name to
model, and set its property to Model. This simple step causes the processAction to be
Chapter 6. Inter-portlet communication
227
called whenever the model property changes. Now copy the following lines of code into
the code editor and save your changes (Example 6-1).
Example 6-1 This simple step causes processAction to be called whenever model property changes
var model = propertyBroker.getProperty("Model").getValue();
sessionScope.selectModel = model;
6. As the next step, open Pages → OrdelList.
7. Next we set up a filter for the rows in the view. Click the view to highlight in, switch to the
Data panel in the Properties tab, and switch Filter to Filter based on the following
dynamic conditions. Copy and paste the following condition. This filter uses the
selectModel variable from the sessionScope to generate the filter. The reason why we
using like instead of = in the query is that we want to be able to use an asterisk (*)
wildcard to retrieve all records if needed.
Example 6-2 This filter uses the selectModel variable from the sessionScope to generate the filter
Model like '#{sessionScope.selectModel}'
Figure 6-11 Creating the view filter
8. Navigate to the beforeRenderResponse event in the Events tab and copy and paste the
following code in the code editor (Example 6-3). This initializes the selectModel variable to
an asterisk (*) so that all records are returned by default.
Example 6-3 Copy and paste this code
if (sessionScope.selectModel == null){
sessionScope.selectModel = "*";
}
228
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Figure 6-12 Creating the beforeRenderResponse event
9. Add a button on the OrderList page that lets users reset the view filter to the asterisk in
order to show all records (which is what the portlet does when it first opens). To do this, go
back to the canvas of the page and add a new button called Show all orders into the
action bar on the page (Figure 6-13). On the Events tab, select the onClick event in the
Mouse category, click Script editor, and select the Server tab on the right. Write the code
shown in Example 6-4 into the OnClick event, as shown on Figure 6-14.
Figure 6-13 Adding the Show All Orders button
Example 6-4 Code
sessionScope.selectModel = "*";
Figure 6-14 Defining the event for the Show All Orders button
10.Save the changes made in the OrderList page.
11.Redeploy your component.
Chapter 6. Inter-portlet communication
229
The WebSphere Property Broker is now able to recognize that your orders portlet can read
the model property. The next step is to configure the WebSphere Property Broker in order to
wire the orders portlet and the chart portlet together.
6.2.3 Configuring the Property Broker
Once you have configured your orders portlet and chart portlet and deployed them to your
portal server, the next step is to wire your two portlets together using the WebSphere
Property Broker. To do this:
1. Log in to the portal with an administrator and navigate to the Orders page.
2. Move the cursor to the top right of the Orders page and click the arrow icon to open up the
page menu.
3. Select Edit Page Layout.
4. Navigate to the Wires tab.
5. In the Portlet Wiring Tool portlet, select Stock Chart in the Source portlet column. The
next column allows you to specify the property that you want to send from your source
portlet. Select model, and then select ITSOCOOL Order System in the target portlet
column. In the Receiving column, select filterOrders,Model.input and select public for
the wire type. This configures the model property to be sent from the stock chart portlet to
the ITSOCOOL order system portlet, and makes the wire accessible to all users.
6. Click the plus icon (+) at the end of the row to add the wire to the page. Your wiring
settings should now appear as shown in Figure 6-15.
Figure 6-15 Completion of wiring settings
7. Click Done to return to the Orders page.
Note: If you are unable to edit any of the columns in the portlet wiring tool portlet, then
WebSphere Portal Express is not able to see that you have any portlets on the page that
use properties compatible with the property broker. Make sure that you have deployed the
updated versions of your portlets from Lotus Component Designer and WebSphere Portlet
Factory, and that you have correctly configured these portlets as described earlier in this
chapter. If you find that you can specify the source portlet but not the target portlet, make
sure that you used the correct namespace in WebSphere Portlet Factory and that you
have the xsd:string data type.
You have now created a wire between the orders and chart portlets. You can test the wire by
clicking a model pie segment in the chart portlet, which should refresh the page and show
details on the model you selected in the orders portlet (note that in order for the wiring to
work, you need to enter orders into the ITSOCOOl order system that match model names in
the stock chart portlet).
Figure 6-16 on page 231 shows a list of orders for the CC 4332 model, which were listed after
the user clicked the pie segment that corresponded to the stock levels for CC 4332. Note that
230
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
if you do not know which model a particular pie segment corresponds to, you can match the
color of the segment with the legend, or move the cursor over the pie segment and read the
pop-up text.
Figure 6-16 A list of orders for the CC 4332 model, which were listed after the user clicked the pie
segment that corresponded to the stock levels for CC 4332
6.3 Conclusion
In this chapter we discussed how developers can use the composite application framework in
WebSphere Portal Express to build composite applications using different technologies. We
demonstrated how to wire together a portlet created in Lotus Component Designer and a
portlet created in WebSphere Portlet Factory using the WebSphere Property Broker, in the
context of the ITSOCOOL ordering system.
If you followed through the steps in this chapter, users of the ITSOCOOL portal will be able to
click a pie chart segment in the stock chart portlet and see the orders for this model in the
ITSOCOOL order system.
Chapter 6. Inter-portlet communication
231
232
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
7
Chapter 7.
Introduction to composite
application framework and
templates
With Portal 6, IBM introduced the concepts of composite applications and application
templates to IBM Portal.
In this chapter we show you the concepts and benefits of this technology. We illustrate in a
step-by-step manner how to create a new template containing pages, portlets, and
components, all of which are included in Portal Express for free. Specifically, we accomplish
the following tasks in this chapter:
򐂰 We make use of the sample applications from Lotus Component Designer, the
announcement portlets, and links portlets from WCM.
򐂰 Once we complete the template, we deploy an application based on this template and
show the steps that need to be done to customize access and content to meet the needs
of the targeted audience.
򐂰 We integrate the portal document manager to store documents.
© Copyright IBM Corp. 2007. All rights reserved.
233
7.1 Overview of customizations to be accomplished in chapter
In earlier chapters, we showed how to build and deploy single components to a portal page.
Now that we know how to deploy single components, the next step is to assemble a reusable
design element containing pages and components that can be used by multiple
organizational units in your company. Reusable design elements containing pages and
components that can be used by multiple organizational units are called a template. From a
template, multiple instance can be created, named composite applications.
7.2 Introduction to composite application framework and
templates
With IBM Portal Version 6 the concept of application templates was introduced to IBM Portal
family. By using templates, composite applications can be reused and instantiated in a very
simple way, providing self-service like capabilities for department-specific or group-based
customizable applications.
Important: Reuse and re-instantiation are two of the key value propositions around
application templates. Templates allow for composite applications to be reused and
instantiated in a very simple way, providing self-service like capabilities for
department-specific or group-based customizable applications.
7.2.1 Explaining terminology and concepts of composite applications and
templates
In this section we explain terminology and concepts of composite applications and templates.
Composite applications
This expression is being used frequently today, but there is not a common definition
explaining exactly what a composite application is. Within this section, we introduce some the
fundamental concepts that apply to composite applications and then show how Portal 6
implements techniques dealing with composite applications and templates.
What is a composite application?
A composite application is an application built by combining multiple services. It consists of
functionality drawn from several different sources within a service-oriented architecture
(SOA). The components may be individual portlets, Web services, selected functions from
within other applications, or entire systems whose outputs have been packaged as Web
services (often earlier systems).
Business approach to composite applications
Composite applications combine new functionality with existing data and applications. The
goal is to deliver new business solutions faster, to respond quickly to market changes or
emerging opportunities. Today IT departments must leverage what already exists, adding
functionality as required, and optimizing business processes to reduce time and cost.
Rather than creating new applications, reuse existing applications and enhance those with
the ability to connect to other processor applications by exposing and consuming them.
234
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
This integration is done in the UI (portal). You can piece together applications to the specific
need or context and integrate applications you never had a chance to previously because
they were too complex or monolithique.
Use what is there, enhance it, and put provide it in a different business context as needed.
This is the goal of composite applications.
A more technical definition for composite applications
In an SOA, discrete business functions are created as independent components with
standard interfaces that can be accessed by other applications, services, or business
processes regardless of the platform or programming language. These services can be
flexibly combined to support different or changing business processes and functions. SOA is
the underlying architecture supporting the creation of composite applications that can be
quickly assembled from existing and new services.
7.2.2 Composite applications in Portal 6 family
This section emphasizes the important distinction between page-based composite
applications and template-based composite applications.
Page-based composite applications
The traditional way that WebSphere Portal applications are created is by assembling portlets
on a collection of related pages that are integrated into the primary MyPortal navigation
hierarchy. These applications are either created by using the Portal-based Web composition
tools or manually created using XML Access. Once they are integrated into the topology there
is no real way to tell them apart from any of the other pages, although there is usually a clear
distinction at development and UX design time. Of course, this style of creating pages is still
fully supported in Portal 6. It is very important to note that there is no reason to stop
developing these kinds of applications if your needs are being met (that is, the new
capabilities are not a replacement for what you are doing now, but are additional tools to
solve additional problems). Access control, page level properties, and portlet entity level
properties can be used to provide a little bit of local context, but all these applications are
essentially running in the global Portal context and leveraging global user roles (for example,
user profile attributes for someone being a manager or global group membership). Wiring
portlets on a page for communication is supported as well. What is missing is a context for all
of the components on the page-like roles and common security or the ability to instantiated
these assemblies.
Template-based composite applications
Application instances are created from templates. A template is a single XML file serialization
of the important aspects of an application instance (and transitively all the contained
component instances). The portal component automatically serializes the entire portal page
topology of the application instance along with all portlet entity properties. Thus, most
standard portlets that use portlet entity properties to store customization state are already
template enabled out of the box. That means that you do not need to rewrite your existing
portlets to leverage them in instance based composite apps.
Templates more detailed
A template describes a composite application in an abstract way, including information that
defines how complex business logic is assembled out of a given set of components. A
template is an XML file that references all components that are used in the template (for
example, portlets or Java code artifacts), and it specifies meta information (configuration such
as specific configuration settings) for each component. You describe the composed
application behavior in the template, and you define the desired interaction between the
Chapter 7. Introduction to composite application framework and templates
235
components, such as wires between portlets. You also define the desired access control logic
to be enforced, such as application-specific user roles. After creating a template, it is stored in
the template library, and you can give permission to specific users to create composite
applications from the templates you provide. In short, a template is an XML file that
represents the abstract definition for an application (that is, it is the blueprint for a composite
application). By using this blueprint you can start creating multiple composite applications
derived from one template with different audiences and different content.
To create a new composite application from a defined template you can pick a template from
the template library and create new instances of the composite application based on the
template definition. The instances run within an application run time, which is referred to as
the composite application infrastructure (CAI). Authorized users (for example, the IT
coordinator of a department) can manage their own application instances, without having the
need of administrative authority.
Figure 7-1 illustrates the concept of templates and composite applications derived from
templates very well. On the left-hand side you start of with your components. By adding
pages, components, user roles, and user access to the template you set up the definition that
is saved to an xml document in the template library. You can now create a composite
application by using these templates.
Business Components
Template
Component
Assembly
Application (Instance)
Instantiation
Template
Instantiation
Service
…
…
XML
XML
XML
XML
XML
Template
Catalog
Collaborative
Application
Infrastructure
(Runtime)
Figure 7-1 Concept of templates and composite applications
236
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
For a more detailed view, Figure 7-2 covers all aspects of templates and applications.
Figure 7-2 Further details of templates and applications
7.2.3 Template features and functions
This section explains the concepts of template parameters, application-level roles, Templates
from instances, and policy-driven management.
Template parameters
Template parameters are a useful tool to allow for instantiation time customization of a new
application instance by the eventual owner. When a new instance is created, a dialog is
presented that asks the creator to specify one or more values (maybe a customer ID, project
ID, or other information applicable to the new context being created). Components use these
instantiation time parameters to affect how they create their own instances and can
automatically adapt their configuration so that they are up and running right away (for
example, use the customer ID to automatically filter a dashboard portlet view for just that
customer).
Application-level roles
Application-level roles can be defined using the application domain language (for example,
for a club, president, treasurer, member, and so on). Application instance access control is
done using these application-level role names, and membership is instance specific. Thus, I
can be the president of one club, and just a member of three others. My user experience and
allowed capabilities depend on my role in the specific instance (even if they were all created
from the exact same template). Transitivity of access control can be accomplished by having
these application-level roles mapped to roles defined by the component, using the
component's domain language. This allows the template assembler to hide the details of the
application domain to component domain mapping from the application instance owner, and
allows component's to be reused in many contexts.
Chapter 7. Introduction to composite application framework and templates
237
Templates from instances
Templates can also be used to capture subsequent organizational learning. As an owner
customizes her instance to more closely match her particular business problem, it may evolve
a long way from the original template. This new instance can then be saved as a template to
capture that learning for reuse in other contexts. Templates can even be used as a unit of
deployment by importing and exporting them from the template catalog.
Policy-driven management
Policy-driven application instance management has been added in Portal 6.0.1 to help to
enforce instance-based quotas and relevance (for example, by archiving instances that have
not been used in a long time) without manual IT intervention. This is done by sending e-mail
to owners and automatically locking the application instance if they go over quota, and
automatically archiving instances based on last used time. This helps an IT organization
manage the infrastructure impact of proliferation of instances.
7.3 Creating and deploying templates
This section discusses how to create and deploy templates.
7.3.1 Portlets associated with templates and applications
To create a template you must have access to different Portal resources. As portal
administrator, you have administrative access to all template and application resources by
default. Figure 7-3 illustrates a listing of these template resources.
Figure 7-3 Access to resources required for template creation
To delegate template creation to non-administrators, you must provide access to the
following resources:
򐂰 Application template portlet
򐂰 Resource permission for application template root
238
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
7.3.2 Easy access fOr Portal Administrator to create a new template
For the Portal administrator it is very easy to create a new template. Starting from the
launchpad you can navigate to the template library by clicking Launch → Templates →
Template Library. See Figure 7-4.
Figure 7-4 Template library
There are to out-of-the-box templates provided with Portal:
򐂰 Documents
With this template you can create instances of the portal document manager libraries as
needed. For example, you can provide each of your departments with a document library
of its own to share documents. This template can be extended by adding pages, portlets,
and components.
򐂰 Portal blank template
This template contains one empty page. By adding content like portlets, components, and
pages to it, you define the template application functionality that is later be provided with
the applications derived from the template.
7.3.3 Steps to provide users with the ability to create application templates
This section describes the resource permissions required and roles that can be assigned to
users for working with templates.
Attention: For additional information about setting these access rights and roles, refer to
the Portal 6 Information Center at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/sec_acc_rights.html
Template access
Use the resource permissions portlet to assign portal access roles to composite application
templates, application template categories, and the application template root.
Access to work with application templates and application template categories is controlled
by the roles that you assign to users using the resource permissions portlet, for example:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Administrator
Security administrator
Delegator
Manager
Editor
Privileged user
User
Chapter 7. Introduction to composite application framework and templates
239
Access rights to work with application templates require a minimum permission of viewing the
Templates page, its child pages (Welcome, Template Library, and Application Library), and
the two portlets, application template library and applications (the application catalog).
Permission to view portal pages and portlets is granted by the role type user.
You can see the application template resources that you need to assign access to by viewing
the resource permissions portlet.
You can do this following this procedure: From the main menu, click Administration, expand
Access, and click Resource Permissions to see these application template resources in the
list of resource types:
򐂰 Application Templates
򐂰 Application Template Categories
򐂰 Application Template Root
Required role assignments for access to application template categories and to application
templates are shown in detail in Table 7-1.
Table 7-1 Access to application template categories
Resource
Operation and description
Required role assignment
Application template categories
Creating a template category
TC
Contributor at template
application document library
Notes:
򐂰 The template application
document library is a single
protected resource of the
type application template
root.
򐂰 Contributor at template
application document
library is the minimum
required access right to
create a template category,
though we do not
recommend it. We
recommend the dditor at
template application
document library to create
and maintain template
categories and use the
portal administration
utilities.
Viewing a template category
TC
240
User at TC.
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Resource
Operation and description
Required role assignment
Application templates
Creating a template from an
existing application
Application manager +
Contributor@TC
Serializing an existing
application A and creating a
new template T under template
category TC
Deploying or importing a new
template T in template category
TC
Note: Contributor@TC is the
minimum required access right
to create a template from an
existing application, though it is
not recommended. Editor@TC
is recommended to create a
template from an existing
application and use the portal
administration utilities.
Contributor@TC +
Editor@Template_Deployment
Notes:
򐂰 Template_Deployment is a
virtual resource.
򐂰 Contributor@TC is the
minimum required access
right to deploy or import a
new template in a template
category, though it is not
recommended. Editor@TC
is recommended to deploy
or import a new template in
a template category and
use the portal
administration utilities.
Creating a new template T in
template category TC
Contributor@TC
Note: Contributor@TC is the
minimum required access right
to create a new template in a
template category, though it is
not recommended. Editor@TC
is recommended to create a
new Template in a Template
Category and use the Portal
administration utilities.
Exporting a template T in
template category TC
User@T +
User@TC
Changing owner of template A
For U1 to change owner to U2,
you need:
򐂰 Delegator@U1
򐂰 Delegator@U2
򐂰 User@U2
򐂰 Delegator@Template
Note: Only the template owner
or an administrator is allowed to
set a new owner.
Chapter 7. Introduction to composite application framework and templates
241
Resource
Operation and description
Required role assignment
Deleting a template T in
template category TC
Manager@T +
Editor@TC
Add group or user access to the application template portlet
To add group or user access to the template application portlet, navigate to
Administration → Portlet Management → Portlets and search for Application Template
Library, as shown in Figure 7-6 on page 243.
Figure 7-5 Adding group or user access to the template application portlet
Click the key symbol on the left and add users/groups to the user role by clicking on the edit
symbol.
Attention: For additional information about setting these access rights and roles, refer to
the Portal 6 Information Center at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/sec_acc_rights.html
242
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Add user access to resource permissions
To add group or user access to resource permissions, navigate to Administration →
Access → Resource Permissions. See Figure 7-6.
Figure 7-6 Resource permissions
Open tHe Application Template Root Resource Permission And Edit Access For The
Template Application Document Library Resource.
7.3.4 Creating the template for our department application
In this example, we used the administrator profile to create the template and later on to create
an application from this template and integrate it into the portal.
The first step in rolling out applications is to create the actual template. In this section, you
learn how to create the template, using all the default settings for the template. At this point,
the template does not actually have the component in it.
Step-by-step: creating a template for your component
To create a template for your component, follow these steps:
1. Log in to the Portal 6 Express environment as administrators or as a user who has
permission to create templates.
2. Click Launchpad → Templates → Template Library.
3. In the Application Template Library portlet, click the New button.
4. Give the template a name that describes its purpose, such as Department Basics.
5. Optional: If you have editor access or higher you can add a new template category. Just
click New Category and complete the form and save it. Now you are able to choose this
category for your template. For each template category you create you must additionally
Chapter 7. Introduction to composite application framework and templates
243
add all users who are allowed to create a template, but not to create categories, as
viewers. This is done by clicking Administration → Access → Resource Permissions.
Then choose Application Template Categories and add the users or groups as
appropriate.
6. Place it in the composite applications category.
7. You can build your template from existing templates or create a new blank one. For this
deployment, you build from the document template (Figure 7-7). Click OK and the
template is created.
Figure 7-7 Template set up page
7.3.5 Template setup
After you created a template, the next step is to modify the default settings. Click the triangle
next to the template name to open the pop-up menu to see all options (Figure 7-8).
Figure 7-8 Editing template properties
Step-by-step: creating pages in templates
These are the steps for setting up your template:
1. From the pop-up menu choose Edit Template Layout.
2. Click New Page to create an additional page for the components we want to add.
3. Label the new page Department News, as shown in Figure 7-8.
4. Edit the new page and change to use the two-column-button layout.
5. Click Add portlet in the left column and add the announcement portlet.
6. Click Add portlet in the right column and add the links portlet.
7. Click Add portlet in the bottom and add the discussion component.
244
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
8. Click Done.
9. On the Layout page, move the new form up so that it becomes the first page by clicking
the up triangle (Figure 7-9).
Figure 7-9 Layout page for portlet placement
Once you have completed defining the portlet layout, you are returned to the application
layout page.
Figure 7-10 Application layout
10.Edit the Documents page, click the add portlet button, and add the FAQs portlet to the
page.
Figure 7-11 Adding the FAQs button to the page
11.Click Done and on the next page click Save. Now your template is completed and
applications can be deployed using this portlet.
Chapter 7. Introduction to composite application framework and templates
245
Step-by-step: editing roles
The portlets and components on this page do not provide any roles, while the template itself
provides two roles: administrators and users. We do not need to modify the administrators
role because it has all permissions. But, we change the users role.
If have you have components that have roles, you must provide these roles for the template
as well. Later on when you create an applications from the template you will associate Portal
groups or users with the roles of the application.
1.
2.
3.
4.
In the pop-up menu of our template choose Manage Roles.
Click users to open it.
Change all entries from No access to User.
Click OK and on the next page and save (Figure 7-12).
Figure 7-12 Editing the users role
Step-by-step: creating default parameters
Parameters specify the property values of the components that are deployed on each page of
the application at run time. In our application, we provide the parameters when we create an
application from the template.
7.4 Creating applications from templates
If you have a groups or users you want to give permission to create applications from your
template you must give them permission to create applications based on the template. In this
section, we create an application based on our template, use the application library, and put
the application on a portal page.
246
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Step-by-step: adding users who can create applications from the
template
To add users who can see the template:
1. From the template library, open the template that you created.
2. From the Directory Search window, add users who are allowed to create an application
based on this template. Click OK.
3. Click Close Template Roles.
Step-by-step: instantiating an application from the template
To instantiate an application from the template, navigate to Launch → Templates →
Application Library (Figure 7-13).
Figure 7-13 Instantiating an application from a template
Click the New button and enter the values for the parameters you want to set.
Every portal can have parameters that you can add values to at instantiation of the
application. These can be of different flavors:
򐂰 Parameters for the document library
Here you define the name and the description of the portal document library this portlet
instance refers to. After the creation of the application, these values cannot be changed
anymore and this portlet instance is tied to one specific doclib. This is different from the
standard PDM portlet where you can select the portal document manager (pdm) library
from a list of libraries you have access to.
򐂰 Parameters for the discussion database
These parameters are provided by the LCD sample application we deployed earlier.
These parameters trigger the look and feel and the behavior of the portlet. With
permissions as application administrator you are able to change the parameters even
after applications was created.
Chapter 7. Introduction to composite application framework and templates
247
򐂰 No parameters
The other portlets we have in our application do not expose parameters to the composite
application infrastructure (CAI), and this is why no parameters for these portlets are shown
on this page. We customize these in one of the next steps.
Figure 7-14 Setting the component properties
Add the values as shown in Figure 7-14 and click OK to instantiate the application from our
template. Now we have added our first application to portal server, namely the sales
department application.
Figure 7-15 Sales department application instantiated from the template
248
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Click the sales department to open the application (Figure 7-16) and take some time to
explore your application. Create some new entries to the discussion database and add some
documents to your document library.
Step-by-step: reviewing the application and adding users and groups
Once you have completed the tasks of adding the sales department application, we explore
the option of reviewing and adding users and groups in our application. To do this, click the
triangle (upper right corner) of the Department News page tab. We discuss the options one by
one.
Figure 7-16 Managing the application roles
In this drop-down list you can edit the application, its members, and its pages. you can see
the actions that are available to you from the drop-down menu of an application page
(Figure 7-16):
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Edit Application Properties
Edit Application Layout
Assign Application Members
Manage Application Roles
Save Application as Template
New Page
Edit Page Layout
Edit Page Properties
Assign Page Permissions
Delete Page
The menu choices that you see depend on the level of access that you have for editing
applications, application membership, and application pages. Each menu choice opens a
portlet where you perform the task. After you open a portlet for an application task, refer to the
Help topics for more information about the task:
򐂰 Application Properties: Use the properties portlet to view and edit the properties of a
composite application. From the drop-down menu of an application page, click Edit
Application Properties to display the properties of the application. Then click Edit to
change application properties that are editable.
򐂰 Application Layout: Use the Application Layout portlet to view, create, and manage pages
of an application. From the drop-down menu of an application page, click Edit
Application Layout to work with the pages of the application.
Chapter 7. Introduction to composite application framework and templates
249
򐂰 Application Members: Assign users and groups to the roles associated with the
application. From the drop-down menu of an application page, click Assign Application
Members to display the members portlet.
򐂰 Application Roles: Use the roles portlet to view and manage the roles for the members of
a composite application. From the drop-down menu of an application page, click Manage
Application Roles. Use the members portlet to add users to the membership list of the
application and assign them roles.
򐂰 Access to applications and components: Specify user access to composite applications,
application pages, and application components by customizing the default membership
roles that are initially displayed in the roles portlet: administrators and users.
򐂰 Application management: Manage composite applications by using a variety of features in
application template libraries, applications catalogs, and portal administration pages.
Note: Managing application pages is similar to working with pages in other work site
contexts, with the following exceptions:
򐂰
򐂰
򐂰
򐂰
Search options are not available.
Navigation is restricted to the selected application.
HTML is the only supported page markup.
URL pages are not supported.
Now we need to give permission to users to access the application. From the drop-down
menu choose Assign Application Members. See Figure 7-17.
Figure 7-17 Give permission to users to access the application
Here you can add users and groups that need access to your application. Add the groups and
user appropriate to you company. For details on how to add users and groups to portal
server, refer to the Portal Express Version 6.0 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
7.4.1 Step-by-step: adding the application to a page
Now that we have completed all steps of creating and managing the application we have one
final step to do. To access the application you have two choices:
򐂰 Open the application from the application library.
򐂰 Add a page to the portal tree and add the application there.
You can put the application library template on any page you want, but if you choose the
option to add a page to the portal tree and add the application there, you must perform some
additional steps:
1. Start your application from the application library.
250
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
2. Copy the URL of you browser.
3. Navigate to Launch → Administration → Portal User Interface → Manage Pages and
go to the tree location where you want to add the new page. We put our page in the ITSO
Cool label.
4. Click New URL.
5. Add My Department as the title.
6. Paste the URL to the HTML field. It is the last field on the page. Click OK.
Figure 7-18 Creating the proper URL link - adding the URL to the HTML field
7. Now navigate to Launch → ITSO cool. You should now have a new tab called My
Department, and if you click it your sales department application opens.
At this point, we have created a new application from a template and added it to our
environment.
7.5 Templates from applications
Templates can be used to capture subsequent organizational learning. As an owner
customizes his instance to more closely match his particular business problem, it may evolve
a long way from the original template. This new instance can then be saved as a template to
capture that learning for reuse in other contexts. We add a additional page to our sales
department application and add a portlet to it and save it as a new template.
Chapter 7. Introduction to composite application framework and templates
251
Step-by-step: add new page and portlet to the application
To add a new page and portlet to the application:
1. Navigate to Launch → Templates → Application Library.
2. Open the Sales Department application.
Figure 7-19 Add a new page and portlet to the application
3. Click the triangle (upper right corner of the Page tab) on the Department News page, as
we did before in the template to add a new page to the application called Contact List.
(See 3.5, “Modifying the contact list sample” on page 98, for more information about the
contact list application.)
4. On this page, change the page layout to one column and add the ContactList portlet to it.
Click Done on the next page, and review your application. It should now have a third page
with the ContactList portlet on it (Figure 7-20).
Figure 7-20 Adding the contact list application to your template page
As we did in 3.5, “Modifying the contact list sample” on page 98 (refer to this section for
specific instructions), customize the header for the contact list to sales contacts, and now you
are done with all changes.
252
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Step-by-step: create a new template from your application
Finally, we now discuss how to create a new template from your existing application.
1. Click the triangle (upper right corner of the Page tab) of one of the pages in the application
and choose Create template from application (Figure 7-21).
Figure 7-21 Create Template from Application
2. Change the name to Department Basics 2 and the text to Basic template with ContactList
added to it. Click OK. With the completion of this step, you have created a new template.
3. Navigate to Launch → Templates → Template Library and look at the new Department
Basic 2 template.
4. Optional step: If you would like create a new application from this template for a different
department (for example, the finance department), use the same steps that we discussed
earlier for deploying our first application. Once done, your new application should look like
that shown in Figure 7-22.
Figure 7-22 Example of a specific department application
Chapter 7. Introduction to composite application framework and templates
253
7.6 Applications and portal policies
Starting with Portal 6.0.1 you can use portal policies to manage your applications derived
from templates.
7.6.1 Introduction to portal policies
Policies in general are used to specify and apply common and specialized settings that
determine the how portal resources function for different classes of users.
A policy is a collection of settings that influences the behavior of a portal resource and the
experience that users have when working with the resource. Policies simplify the
management of portal resources because the policy settings for a resource type can control
the behavior of the resource for different classes of users. For sites that comprise large
numbers of users and resources, specifying and applying policies to portal resources
eliminates much time-consuming effort that would otherwise require administrators to
manage a vast array of discrete settings for users and resources.
Policies are grouped according to the types of resources that apply the policies and follow a
hierarchical model that supports inheritance. For each type of portal resource that you
manage with policies, you can specify standard policy settings that support the uniform
business processes, as well as specialized policy settings that support business process
refinements for a variety of routine and exceptional conditions. That is, you can refine the
main policies that are provided for portal resources by creating child policies that inherit or
override the policy settings of the parent policy. You reuse common and specialized business
logic when you select the policy rules and conditions that constitute child policies created
from parent policies. When you edit the policy settings of a resource, you can choose to
preserve or break the inheritance of policy setting values between parent and child policies.
The policy settings for a particular type of portal resource are defined in the XML document
that specifies the policy type, its settings, its rules, and its targets. Policy rules contain the
business logic, expressed as conditional statements, that drives your business processes
and determines how portal resources function for a class of users. The policy definition
contains references to one or more rules that describe the actions that occur on a target user
or object when specific conditions exist. The events or conditions that must be evaluated for
the resource and the actions performed on the resource are expressed in the rules and
presented in the policy settings. The policy settings for a resource are evaluated by the
personalization rules engine. When you create or modify child policies, you work with the
personalization browser, which provides the rule editor and rule selector for working with
policy rules.
254
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
7.6.2 How policies apply to composite applications
In Table 7-2 all parameters of the default composite applications policy are listed. Take some
time to review the parameters. This policy can be applied to application templates and to
composite applications. By adding new subpolicies and applying these to the template or
application of your choice you can fine-tune the settings as desired.
Table 7-2 Policy settings for composite applications
Setting
Description
Default value
Allow changes in
children
Monitor application
size
Enable or disable the
monitoring of
application size.
Enable
No
Maximum application
size
Specify in MB the
maximum size allowed
for the application.
100
Yes
Application size
warning threshold
Specify a percentage
of the maximum
application size. When
this value is reached, a
warning is sent
informing recipients
that the application
exceeds its size limit.
90
Yes
Application size
warning action
Specify the warning
action that occurs
when the application
size threshold is
reached.
򐂰
Specify the action that
occurs when the
application exceeds
the maximum size
allowed.
򐂰
Monitor modification
frequency
Enable or disable the
monitoring of when the
application was last
modified.
Enable
No
Application no-modify
period
Specify the number of
days that the
application is allowed
to stand without
modification.
120
Yes
No-modify warning
threshold
Specify the number of
days that the
application is allowed
to stand without
modification before a
warning is sent.
30
Yes
Application size
violation action
򐂰
򐂰
򐂰
Send e-mail to
administrators.
Send e-mail to
application owner
Yes
Send e-mail to
administrators.
Send e-mail to
application owner.
Lock application to
users, except
administrators and
application
owners.
Yes
Chapter 7. Introduction to composite application framework and templates
255
Setting
Description
Default value
No-modify warning
action
Specify the warning
action that occurs
when the application
no-change threshold is
reached.
򐂰
Specify the action that
occurs when the
application exceeds
the no-change period.
򐂰
Monitor application
activity
Enable or disable the
monitoring of when the
application was last
accessed.
Enable
No
Maximum inactivity
period
Specify the number of
days that the
application is allowed
to stand without being
accessed.
120
Yes
Inactivity warning
threshold
Specify the number of
days that the
application is allowed
to stand without
activity before a
warning is sent.
30
Yes
Inactivity warning
action
Specify the warning
action that occurs
when the application
non-use threshold is
reached.
򐂰
Specify the action that
occurs when the
application exceeds
the non-use limit.
򐂰
No-modify violation
action
Inactivity violation
action
򐂰
򐂰
򐂰
򐂰
Allow changes in
children
Send e-mail to
administrators.
Send e-mail to
application owner.
Yes
Send e-mail to
administrators.
Send e-mail to
application owner.
Yes
Send e-mail to
administrators.
Send e-mail to
application owner
Yes
Send e-mail to
administrators.
Send e-mail to
application owner.
Yes
Now we show you where policies for composite applications are located, how to modify the
default policy, and how to add child policies.
256
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Step-by-step: working with composite application policies
From the main menu, click Administration → Access → Resource Policies to create and
manage policies for composite applications. Starting with the main policy for composite
applications, you can create child policies for subsets of applications (Figure 7-23).
Figure 7-23 Creating and defining policies
If you click the policy menu (small triangle) of the Composite applications policy you see four
options (Figure 7-24).
Figure 7-24 Defining policies
The options are:
򐂰 Edit Policy: Here you can change all parameters shown in Table 7-2 on page 255. You can
also choose whether the parameters are set for child policies as well.
򐂰 Import Policy Definition: Just like templates, policies are xml based as well and you can
import an xml policy file to your policy store.
򐂰 Export Policy: With this option you generate an xml file that contains the policy rules of the
exported policy.
򐂰 Assign User Access to Policy: Just like templates, you can set access to policies to allow
users to read or change policies.
Chapter 7. Introduction to composite application framework and templates
257
Step-by-step: editing the default composite application policy
To change the default settings use the Edit Policy option, as shown in Figure 7-25. Change
the parameter for maximum application size from 100 MB to 120 MB and save the policy by
clicking OK at the bottom (Figure 7-25).
Figure 7-25 Editing policy parameters
To review the change you have made, open the application you created earlier (sales
department application). Open the application menu as described earlier and select the
Manage Application Roles option. Here you should see the changed parameter. If you do
not see this change, click Update Status (Figure 7-26).
Figure 7-26 Click the Update Status button
258
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Step-by-step: creating a policy rule as the first step for adding a child
policy to the default composite application policy
The default composite application policy can be fine tuned by adding child policies. Here we
show what needs to be done to add child policies to the default composite application policy.
To specialize the default policy for composite applications, you create child policies. Child
policies help you manage subsets of applications. Click the Composite Application policy
link to display the portlet view where you can create a new policy based on an existing policy
rule or a new rule that you create. The new policy is a child policy of the default composite
application policy. Before you can create a child policy, you must create or select a policy rule
that expresses the conditions that you need for the new policy. From the policy rule
drop-down menu, click Create New Rule or Select Rule to display the personalization editor.
Each rule contains one or more conditions. See Figure 7-27.
Figure 7-27 Defining rules within the personalization picker
Here we named the new policy department, but this could be anything, as it is just a
placeholder. Now we associate a new policy for a policy we create next with an attribute we
put into the policy selection attribute of our application. Because we have the sales
department as an example, we call the rule sales and the rule as well. To fill in the
parameters:
1. For the profile attribute enter Sales and click the Submit button.
2. For the attribute click attribute an choose Composite Application → Policy Selection
Attribute (Figure 7-28).
Figure 7-28 Policy selection attribute
Chapter 7. Introduction to composite application framework and templates
259
3. Set the attribute value to Sales.
4. Click Save to store this rule.
Step-by-step: adding a child policy to the default composite application
policy
Now that we have added the policy rule we can add a new child policy. Click the Composite
Application policy. You now enter a new view. Here click New policy.
As the policy name enter Sales, and for the policy condition select Sales from the drop-down
menu. You see the policy conditions, as shown in Figure 7-29.
Figure 7-29 Policy conditions
Change the parameter maximum application size to 140 MB. To do this first uncheck the Use
Parent Value check box for this parameter. Then enter 140 for the value and click OK at the
bottom of the page. Now we have created a child policy. You can add additional policies and
you can create a child to this policy.
Step-by-step: associating a composite application or a template with a
policy
Now that we have created a policy we can associate this policy with a template or application.
In our example we associate the sales department application with the sales policy status.
Navigate to the sales department application and open the application menu. Select Show
Policy Value. We have done this before when we changed the default policy.
260
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Now review the policy selection attribute. It should have the value CompositeApplication.
Click Edit (Figure 7-30).
Figure 7-30 Modifying the policy selection attribute
Here, change the policy selection attribute to Sales and click OK.
You are returned back to the show policy status. Review the maximum application size value.
It should have changed to the value you set in your sales policy. If not, check whether sales is
set as the policy selection attribute. If yes, click the Update Status button or check the value
in your policy.
Summary
In this section, we discussed what policies are and the effect that they have on templates and
composite applications. Here some of the many features you can use:
򐂰 Use policies to monitor applications and set values and actions to be informed about
reaching thresholds or violations.
򐂰 Auto archive applications not used for a specified amount of time.
򐂰 Create child policies of many levels.
򐂰 Associate policies with templates and composite applications created from these
templates inherit this policy.
򐂰 Associate a policy at any time to a composite application or create a policy for each
application individually.
7.7 Deploying templates
You can deploy a composite application template to another sever by exporting and importing
the template XML file from the source server to the target server. Use the application
template library on the source server to export the template XML file. Use the application
template library on the target server to import the template XML file.
After you create or customize an application template, you can export it for use on another
server.
Note: You can only import the template you exported to a portal server with the same or a
higher release, for example, from 6.0.0.1 to 6.0.0.1 or 6.0.1
Chapter 7. Introduction to composite application framework and templates
261
Step-by-step: exporting a template to an xml file
In the application template library, find the template that you want to deploy on another server
and open its drop-down menu (Figure 7-31).
Figure 7-31 Find the template that you wish to export
From the menu of the template, click Export Template and save the template as an XML file
in your file system (Figure 7-32).
Figure 7-32 Prompt to save the exported XML file
Step-by-step: importing a template to an xml file
Move the file to the file system of the server on which you want to deploy the template.
Now you can import the template to another system. For the case in which you do not have a
second portal server we just rename the template while importing it the portal server exported
from.
1. Navigate to Launch → Templates → Template Library.
2. Click Import and browse the local file system to find the XML template file (Figure 7-33).
Figure 7-33 Importing the XML File
262
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
3. When you click OK a warning appears because this template already exists on the portal
server. Change the name of the template to Our Test Import Template and click OK.
(See Figure 7-34.)
Figure 7-34 Change the name of the template
Now we have imported the template to our portal server and you can use it like any other
template.
Figure 7-35 List of templates
Chapter 7. Introduction to composite application framework and templates
263
Attention: Adding composite applications to portal search collections
While we do not cover this topic in extensive detail, we want to bring this to your attention
Add composite applications to portal search collections to enable the searching of content
in application pages and portlets.
Before you begin, understand the capabilities provided by portal search and create at least
one search collection. Consider creating a search collection specifically for the composite
applications running on one portal site.
To add the pages and portlets of composite applications to a portal search collection,
follow the procedure for customizing a search collection for secured portal pages.
Note: The content of a composite application comprises the application, its pages, and the
portlets on each page. The application, its pages, and its portlets must be accessible to the
user that you create to be the content crawler of the search collection. Therefore, be
certain that the content crawler user is assigned an application role that permits the
appropriate level of access to the pages and portlets of the composite applications that you
include in the portal search collection. Portal search results vary according to the
application roles assigned to the content crawlers that you create for each search
collection.
264
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
A
Appendix A.
Installation and configuration
best practices
This appendix describes some best practices that will help you to install, upgrade, and
configure your portal server.
This appendix is not a replacement for the installation, upgrading, or configuration sections of
the InfoCenter. It is intended only to supplement the information center, as it provides you
with hints and best practices on how to succeed quickly.
Always read the InfoCenter carefully before performing installation steps. The information
Center for Portal 6 Express can be found at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
Important: For information about using the Domino-WebSphere Portal Integration wizard,
refer to the Portal 6.0.1 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/inst_updates.html
From within the InfoCenter, search on the text Domino-WebSphere Portal Integration
wizard overview.
© Copyright IBM Corp. 2007. All rights reserved.
265
Upgrading Portal Server from 6.0.0.1 to 6.0.1
Important: For information about upgrading your environment from Portal 6.0 Express to
Portal 6.0.1 Express, refer to the Portal 6.0.1 Information Center:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/inst_updates.html
To upgrade the portal server:
1. Upgrade WebSphere Application (WAS) Server’s Java SDK using the WAS Update
Installer. Everything you need you find is in the
6.0.2-WS-WASJavaSDK-WinX32-FP0000009.zip file, which is available for download
from:
http://www.ibm.com
2. Install all necessary fixes:
–
–
–
–
–
–
PK32424
PK34800
PK40359
PK41358
PK32069
PK37272
You can find all the fixes listed below conveniently in the
6.0.1-WP-WSASv6.0.2.17-IFPackage.zip file, which is available for download from:
http://www.ibm.com
Tip: On Windows operating systems, fixes can be installed easily by double-clicking
each of them (one file is one fix) if the .PAK file type is registered in the operating
system. If it is not, you can register the latest version of the portal update installer from
http://www.ibm.com (file name PortalUpdateInstaller.zip) and install it.
3. Prepare necessary passwords for the update installer in the configuration files of
WebSphere Portal Server.
In the Portal Server’s installation directory, open wpconfig.properties in a text editor,
search for ReplaceWithYourWASUserPwd, and replace it with your WebSphere Application
Server administrator’s password (that you specified during the portal server installation).
If you are using DB2, in the portal server’s installation directory, open wpconfig_
dbdomain.properties in a text editor, search for ReplaceWithYourDbAdminPwd, and
replace it with your DB2 administrator’s password (that you specified during the Portal
Server installation).
Download and run the Portal Server Upgrade Wizard. It can be downloaded from the
6.0.1-WP-Multi-RP001.zip file at:
http://www.ibm.com
Attention: On Windows operating systems, the Update Installer may fail to start and
stop WebSphere Portal Server and Application Server if they are enabled Windows
services. If you encounter this problem, go to Windows services and disable IBM
WebSphere services during the update installation.
266
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Enabling LDAP security with the configuration wizard
The simplest way to enable LDAP security is to run the WebSphere Portal Express
configuration wizard. You can do it by executing the following script file:
<portal_install_root>/config/wizard/configwizard.bat
Important: If you are using the WebSphere Portal Express configuration wizard to enable
LDAP security, when specifying user IDs, never leave the organization part empty. Always
specify the user name in the format:
cn=wpadmin,o=organization
Sametime integration
When running the Sametime installation wizard, be sure to select the LDAP option and not
Domino directory.
Before you test Sametime from the Notes client:
򐂰 Go to the test user’s person document and fill in the Sametime server’s name in full
canonical format, such as cn=server/o=acme.
򐂰 If testing Sametime in the Notes client, edit the current location document and fill in the
Sametime server name in the appropriate field on the Servers tab.
Important: Log on to Sametime using the user’s short name, not his/her full canonical or
abbreviated name. (Sametime is searching for the user’s short name or e-mail address
when authenticating through LDAP. This can be changed in the Sametime Configuration
database, if needed.)
Once you have installed and tested Sametime, you are ready to run the Domino Integration
wizard, which integrates Sametime into your WebSphere Portal Express automatically.
Using the Domino Integration wizard
The Domino Integration wizard is a tool that is new in WebSphere Portal Express Version
6.0.1. The wizard does the following tasks for you:
򐂰 Domino and WebSphere Single-Sign-On (SSO)
򐂰 Domino Collaborative components (mail, calendar) integration
򐂰 Sametime (people awareness) integration
The next steps describe the best practices when running the Domino Integration wizard. Be
sure to read the InfoCenter carefully to ensure that all prerequisites are met before running
this wizard.
1. Pay attention to the TechNote in the InfoCenter, which discusses existing SSO
documents. If you have installed Sametime on Domino before with the Sametime
Installation wizard, an SSO document has been created for you, which you will have to
delete before you can successfully run the Domino integration wizard.
Appendix A. Installation and configuration best practices
267
This is a very important step, so let us point out the necessary steps here:
a. In Domino Administrator, open the Current server document, go to the Internet
Protocols → Web Engine tab and set Session authentication to Disabled.
b. In Domino Administrator, open the Server → Configuration view and remove the
SSO document for the current server.
2. To ensure that the new SSO document is created properly, check that the LTPA settings
on you WebSphere Application server are correct. You can do it this way:
a. Ensure that your WebSphere Application Server is running.
b. Go to WebSphere Application Server’s Administrator interface (by default available on
https://<your_domain>:10039/admin). Pay attention to the https at the beginning.
c. Log in using your application server administrator’s user name and password.
d. From the left menu select Security → Global security.
e. In the right frame click Authentication → Authentication mechanisms → LTPA.
f. Now click Additional Properties → Signel Sign On (SSO).
g. Verify that your domain name is not empty.
h. If it is empty, fill in your domain name for single sign on. It is usually your fully qualified
DNS name without your host name on the left side (for example, if host.domain.com is
your host name then domain.com is your domain name).
i. If you made any changes in the domain name, save your changes carefully and restart
the application server.
3. Once you are done verifying the SSO configuration, you need to set up the DPICFG.NSF
database.
a. From the <portal_install_dir>\config\wizard directory copy the file called dpicfg.nsf into
the root of your data directory on the Domino server.
b. From a Notes client or the Domino Administrator, configure the Access Control List
(ACL) of the dpicfg.nsf database. Add the Domino server’s Administrator as a person
with manager access level to the ACL of the database.
Note: Alternatively, you can use another user ID as well, provided that it has
permissions to edit the names.nsf database on the server and it also has
personations to run restricted LotusScript/Java agents on the server. Be sure to use
a real user ID that was created by the Domino administrator who has a valid
certificate in his person document. If you try to use a manually created person
document then the integration will fail because of the invalid certificate.
Important: Do not give anonymous or default manager access to the dpicfg.nsf
database because integration will fail. You have to use a real user ID.
4. Now you are ready to run the Domino Integration wizard. Execute the following script
(example shows Windows OS):
<portal_install_root>/config/wizard/dpiwizard.bat
268
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
B
Appendix B.
Configuring the ITSOCOOL
environment
This appendix discusses how to configure your environment for the ITSOCOOL scenario
discussed throughout this paper. The following areas are covered:
򐂰 Setting up a stock database in DB2
򐂰 Installing and running a Web service to serve up supplier information
It is possible to follow through the examples in this paper with different Web services and data
stores, although note that if you do this many of your settings will be different, and some of
the steps might change (for example, if you use a non relational data store instead of DB2).
© Copyright IBM Corp. 2007. All rights reserved.
269
Setting up a stock database in DB2
The stock database is used throughout this paper as a backend data store for portlets built in
both Lotus Component Designer and WebSphere Portlet Factory. Setting up the stock
database involves creating the ITSOCOOL database in DB2, and then setting up a JDBC
resource in WebSphere Portal Express that can be accessed by both Lotus Component
Designer and WebSphere Portlet Factory.
The first step is to create the stock database in DB2. To do this:
1. Start the DB2 Command Editor on the portal server.
2. Fill out the SQL command as shown in Figure B-1 into the first edit pane. This command
creates a new database called ITSOCOOL, and create a STOCK table inside the
database.
Figure B-1 Fill out SQL command
3. Click the Play button to execute the SQL. The results of running the SQL display in the
bottom pane. You should see results similar to Example B-1.
Example: B-1 Results
CREATE DATABASE ITSOCOOL;
CONNECT TO ITSOCOOL;
CREATE TABLE "ADMINISTRATOR"."STOCK" (
"SUPPLIER" VARCHAR(100) NOT NULL ,
"MAKE" VARCHAR(100) NOT NULL ,
"MODEL" VARCHAR(100) NOT NULL ,
"QUANTITY" BIGINT NOT NULL ,
"OWNER" VARCHAR(100) NOT NULL ,
"DESCRIPTION" VARCHAR(100) NOT NULL ,
"PRICE" BIGINT NOT NULL )
IN "USERSPACE1" ;
COMMENT ON TABLE "ADMINISTRATOR"."STOCK" IS 'holds a list of all items in stock';
270
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
ALTER TABLE "ADMINISTRATOR"."STOCK"
ADD CONSTRAINT "MAKE_MODEL_PK" PRIMARY KEY
("MAKE", "MODEL");
COMMIT WORK;
CONNECT RESET;
TERMINATE;
-----------------------------------------------------------------------------CREATE DATABASE ITSOCOOL
DB20000I The CREATE DATABASE command completed successfully.
CONNECT TO ITSOCOOL
Database Connection Information
Database server
SQL authorization ID
Local database alias
= DB2/NT 9.1.0
= ADMINIST...
= ITSOCOOL
CREATE TABLE "ADMINISTRATOR"."STOCK" ( "SUPPLIER" VARCHAR(100) NOT NULL , "MAKE"
VARCHAR(100) NOT NULL , "MODEL" VARCHAR(100) NOT NULL , "QUANTITY" BIGINT NOT NULL
, "OWNER" VARCHAR(100) NOT NULL , "DESCRIPTION" VARCHAR(100) NOT NULL , "PRICE"
BIGINT NOT NULL ) IN "USERSPACE1"
DB20000I The SQL command completed successfully.
COMMENT ON TABLE "ADMINISTRATOR"."STOCK" IS 'holds a list of all items in stock'
DB20000I The SQL command completed successfully.
ALTER TABLE "ADMINISTRATOR"."STOCK" ADD CONSTRAINT "MAKE_MODEL_PK" PRIMARY KEY
("MAKE", "MODEL")
DB20000I The SQL command completed successfully.
COMMIT WORK
DB20000I The SQL command completed successfully.
CONNECT RESET
DB20000I The SQL command completed successfully.
TERMINATE
DB20000I The TERMINATE command completed successfully.
You have now successfully set up the stock database in DB2. You can add records to the
database by using the stock portlet created in 4.4, “Creating the stock control component” on
page 158, or using the DB2 Control Center.
The next step is to set up the JDBC resource on the portal server so that Lotus Component
Designer and WebSphere Portlet Factory can talk to the ITSOCOOL database. To do this:
1. Log in to the administration console for your WebSphere_Portal instance by typing in the
following command into a Web browser:
https://localhost:10039/ibm/console/logon.jsp
Note that this URL might differ if you did not install WebSphere Portal Express with the
default settings. If you do not know the URL for your admin console, you can instead run
the admin console for your application server from the IBM WebSphere entry in your Start
Appendix B. Configuring the ITSOCOOL environment
271
Menu (as shown in Figure B-2.), although this also requires you to start the server1
instance first.
Figure B-2
2. Navigate to JDBC Providers in the admin console, as shown in Figure B-3.
Figure B-3 Navigate to JDBC Providers
3. Click the Browse Servers button next to the Server box.
4. Select WebSphere_Portal on the next window, and click OK.
5. Click the New button.
6. Select DB2 as the database type.
7. Select DB2 Universal JDBC Driver Provider for the provider type.
8. Select Connection pool data source for the implementation type. Click Next.
9. Change the class path and native library path fields so that they point to the location of the
DB2 jar files listed. These files are not located in the directory specified in the
DB2UNIVERSAL_JDBC_DRIVER_PATH environment variable by default, although they
come with WebSphere Portal Express in the db2\java directory. You can either move
these files into the directory specified by the environment variable, or move them into a
different folder and specify this in the admin console (we demonstrated how to do this in
Figure B-4).
Figure B-4 Change class path and native library path fields
272
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Click OK.
10.Click Save (see Figure B-5).
Figure B-5 Save
11.The DB2 Universal JDBC Driver Provider now appears in the JDBC Providers list. Click
the DB2 Universal JDBC Driver Provider link, as shown in Figure B-6.
Figure B-6 Click link
12.Click the Data Sources link under the Additional Properties heading.
13.Click the New button.
14.Give the data source a meaningful name. We have use ITSOCOOL in the example.
15.Change the JNDI name to jdbc/ITSOCOOL.
16.Scroll down to the DB2 Universal data source properties section. Enter ITSOCOOL for the
database name you would like to connect to, and then the host name of your portal server
in the Server name box. The settings we used are shown in Figure B-7.
Figure B-7 Our settings
Click OK.
17.Click Save, and then when the window reloads click the Save button again.
Appendix B. Configuring the ITSOCOOL environment
273
18.The ITSOCOOL data source should now show up in the data source list (see Figure B-8).
Click the ITSOCOOL link to configure the data source.
Figure B-8 JDBC Providers
19.Click J2EE Connector Architecture (J2C) authentication data entries underneath the
Related Items heading.
20.Click New. This creates a new authentication entry, which we use to connect to the data
source.
21.Enter an alias for the authentication entry and fill out the user name and password details
as you configured them when you installed WebSphere Portal Express. We used the
settings shown in Figure B-9.
Figure B-9 Settings
Click OK.
22.Click Save, and then when the window reloads click the Save button again.
23.Navigate back to the IT SOCOOL data source by clicking the ITSOCOOL link at the top of
the window (see Figure B-10).
Figure B-10 Click link
24.Scroll down to the Component-managed authentication alias section, and select the
authentication alias you created earlier from the drop-down. Click OK.
25.Click Save, and then when the window reloads click the Save button again.
274
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
26.Test your connection by selecting ITSOCOOL and clicking the Test connection button, as
shown in Figure B-11. If your connection test is failing, make sure that your user name and
password are correct in the authentication alias, and make sure that the db2 jar files are
specified correctly on the JDBC resource page.
Figure B-11 Test connection
27.You may need to restart the WebSphere_Portal instance. To do this, type:
[WebSphere Portal Express root]\AppServer\bin\stopserver WebSphere_Portal
Where [WebSphere Portal Express root] is the root directory of your portal installation.
Once your portal server has stopped, type:
[WebSphere Portal Express root]\AppServer\bin\startserver WebSphere_Portal
Where [WebSphere Portal Express root] is the root directory of your portal installation
(Note that if you are going to follow through to the next section and set up the Web service
as well, you should leave the WebSphere_Portal instance running.)
Once you have completed these steps and tested your data source, the ITSOCOOL
database is ready to be accessed by Lotus Component Designer and WebSphere Portal
Express.
Installing and running a Web service to serve up supplier
information
To access supplier information from your Lotus Component Designer components, you need
to install and run a suppliers Web service into WebSphere Portal Express. You can download
the ITSOCOOL suppliers Web service from the additional materials provided with this
Redpaper:
ftp://www.redbooks.ibm.com/redbooks/REDP4316/
To install the ITSOCOOL suppliers Web service:
1. Make sure that the WebSphere_Portal instance is started. You can start the
WebSphere_Portal instance by typing in the following command at a command prompt:
[WebSphere Portal Express root]\AppServer\bin\startserver WebSphere_Portal
Where [WebSphere Portal Express root] is the root directory of your portal installation.
2. After WebSphere_Portal starts, log in to the administration console by typing the following
command into a Web browser:
https://localhost:10039/ibm/console/logon.jsp
Appendix B. Configuring the ITSOCOOL environment
275
Note that this URL might differ if you did not install WebSphere Portal Express with the
default settings. If you do not know the URL for your admin console, you can instead run
the admin console for your application server from the IBM WebSphere entry in your Start
menu (as shown in Figure B-2 on page 272, although, this also requires you to start the
server1 instance first.)
3. Navigate to the Install New Application entry in the admin console, as shown in
Figure B-12.
Figure B-12 Install New Application entry
4. Enter in the location of the EAR file you downloaded from the ITSO site, as shown in
Figure B-13.
Figure B-13
Click Next.
5. The next window allows you to specify default bindings and mappings. Accept the defaults
by clicking Next.
6. The next window allows you to specify installation options. Accept the defaults by clicking
Next.
276
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
7. On the next window, you need to specify that you want the application installed to
WebSphere_Portal. To do this, check the box next to the ITSOCOOL_WS_Resource,
select the second entry in the Clusters and Servers drop-down list, and then click Apply,
as shown in Figure B-14. Click Next when finished.
Figure B-14 Install New Application window
The next window allows you to specify options for virtual hosts. Accept the defaults by
clicking Next. Click Finish.
8. Click Save to master configuration.
9. Click the Save button.
The ITSOCOOL suppliers Web service is now installed on WebSphere_Portal, but is not
started by default. To run the ITSOCOOL suppliers Web service:
1. Select Enterprise Applications in the admin console, as shown in Figure B-15.
Figure B-15 Select Enterprise Applications
Scroll down through the list of installed applications to find the ITSOCOOL suppliers Web
service (called ITSOCOOL_EAR).
2. Check the box next for ITSOCOOL_EAR and click the Start button.
You have now successfully installed and run the ITSOCOOL suppliers Web service.
Appendix B. Configuring the ITSOCOOL environment
277
278
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
C
Appendix C.
Additional material
This paper refers to additional material that can be downloaded from the Internet as
described below.
Locating the Web material
The Web material associated with this paper is available in softcopy on the Internet from the
IBM Redbooks Web server. Point your Web browser at:
ftp://www.redbooks.ibm.com/redbooks/redp4316
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with the IBM
Redpaper form number, REDP4316.
Using the Web material
The additional Web material that accompanies this paper includes the following files.
Table 7-3
File name
Description
AdditionalMaterial_4316
A single zip file that contains each of the files
listed below. Download this if you wish to have all
the sample files and not download any files
individually.
Basic_Customizations.zip
The files needed to complete the customizations
in Chapter 2, “Introduction to customization in
WebSphere Portal Express” on page 15.
© Copyright IBM Corp. 2007. All rights reserved.
279
280
File name
Description
DB2_Sample_Database Script.zip
A SQL script for DB2 that creates a new
ITSOCOOL database, with a table called
SUPPLIERS.
Intro_to_LCD.zip
The files needed to complete the customizations
in Chapter 3, “Introduction to Lotus Component
Designer” on page 85.
Lotus_Component_Designer_Components.zip
All files needed to perform the customizations
(including the completed sample components)
created in Chapter 4, “Customization using Lotus
Component Designer” on page 129.
Themes.zip
ITSO Cooling Co. (ITSOCool) sample theme.
Web_Service.zip
Web Service used in Chapter 4, “Customization
using Lotus Component Designer” on page 129.
WebSphere_Portlet_Factory_Models.zip
Models used in Chapter 5, “Customization using
WebSphere Portlet Factory” on page 199.
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Related publications
The publications listed in this section are considered particularly suitable for a more detailed
discussion of the topics covered in this paper.
IBM Redbooks
For information about ordering these publications, see “How to get Redbooks” on page 281.
Note that some of the documents referenced here may be available in softcopy only.
򐂰 WebSphere Portal Version 6 Enterprise Scale Deployment Best Practices, SG24-7387
򐂰 Installing and Configuring WebSphere Portal Express V6 on i5/OS, REDP-4303
Online resources
These Web sites are also relevant as further information sources:
򐂰 Portal Express Version 6.0 Information Center
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.exp.doc/wpf/welcome.html
How to get Redbooks
You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications
and Additional materials, as well as order hardcopy Redbooks, at this Web site:
ibm.com/redbooks
Help from IBM
IBM Support and downloads
ibm.com/support
IBM Global Services
ibm.com/services
© Copyright IBM Corp. 2007. All rights reserved.
281
282
WebSphere Portal Express - Customizing Portal Express for Small to Medium Business
Back cover
®
WebSphere Portal Express
Customizing Portal Express
for Small to Medium Business
Customizing your
Portal Express
Environment to meet
business needs
Using Lotus
Component Designer
to build a custom
component
Deploying
applications through
templates
This IBM Redpaper provides a hands-on example of how to customize
solutions for your small and medium business using WebSphere Portal
Express, Lotus Component Designer, and WebSphere Portlet Factory.
This paper introduces and builds upon a specific scenario and sample
application, then shows how to achieve basic, intermediate, and
advanced levels of customization using the options within WebSphere
Portal Express, Lotus Component Designer, and WebSphere Portlet
Factory. The key topics of this paper are:
򐂰 Introduction to WebSphere Portal Express
򐂰 The options for customization in WebSphere Portal Express
򐂰 Basic customization, focusing on how to customize Web sites,
logos, themes, and skins
򐂰 More advanced customization using Lotus Component Designer
򐂰 Building and deploying components using Lotus Component
Designer
򐂰 More advanced customization using WebSphere Portlet Factory
򐂰 Building on above scenario, but adding backend lookup built using
WebSphere Portlet
򐂰 Building and deploying component within WebSphere Portlet
Factory
Redpaper
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed
by the IBM International
Technical Support
Organization. Experts from
IBM, Customers and Partners
from around the world create
timely technical information
based on realistic scenarios.
Specific recommendations
are provided to help you
implement IT solutions more
effectively in your
environment.
For more information:
ibm.com/redbooks
REDP-4316-00
™