Front cover
IBM Workplace 2.5
Development with
Workplace Designer
Overview of Workplace Designer
features and benefits
Creating a component and using
the design elements
Building a sample
application
John Bergland
Adam Egressy
Nick Orrick
Marc Weinzetl
ibm.com/redbooks
Redpaper
International Technical Support Organization
IBM Workplace 2.5 Development with Workplace
Designer
December 2005
Note: Before using this information and the product it supports, read the information in “Notices” on
page vii.
First Edition (December 2005)
This edition applies to IBM Workplace Designer, version 2.5
© Copyright International Business Machines Corporation 2005. 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 Redpaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Additional contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Chapter 1. Introduction to IBM Workplace Designer Version 2.5 . . . . . . . . . . . . . . . . . . 1
1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1 Workplace Designer features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Business value and key advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Developer audience for Workplace Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Overview of tools for customizing Workplace applications . . . . . . . . . . . . . . . . . . . . . . . 6
1.5 Positioning between Workplace Designer and Application Template Editor. . . . . . . . . . 6
1.5.1 Workplace Designer and Workplace Application Template Editor: What is the
difference? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.2 Terminology of key concepts for Workplace applications . . . . . . . . . . . . . . . . . . . . 8
1.6 Introduction to the sample application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.6.1 Sample application overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.7 Approach used to develop the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2. Features and functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1 Overview of features in Workplace Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Overview of design elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2 Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.3 UI controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.4 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Setting up the development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Basic installation steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Sample application: Status reporting component . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.1 Sample application overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.2 Sample scenario: Application details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.3 Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
16
16
16
17
18
20
20
21
22
23
26
27
Chapter 3. Developing the sample application: Basic development topics . . . . . . . .
3.1 Creating a Workplace component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Step-by-step: Creating a component from scratch . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Creating a schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Step-by-step: Creating the status report schema . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Creating a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Step-by-step: Creating a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Creating buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 Step-by-step: Adding buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Creating a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1 Views versus view controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.2 Step-by-step: Creating a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
30
31
32
33
37
38
42
43
51
51
52
© Copyright IBM Corp. 2005. All rights reserved.
iii
3.5.3 Other information about view properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Data validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.1 Step-by-step: Adding validation to the status report application . . . . . . . . . . . . . .
3.7 Deploying and testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.1 Step-by-step: Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2 Step-by-step: Component test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
65
65
68
68
69
Chapter 4. Developing the sample application: Intermediate development topics . . 73
4.1 Response documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4.1.1 Step-by-step: Adding a task view to the status report. . . . . . . . . . . . . . . . . . . . . . 74
4.2 Optional: Dynamic combo boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.2.1 Step-by-step: Creating the dynamic combo box . . . . . . . . . . . . . . . . . . . . . . . . . . 82
4.3 Adding workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.3.1 Step-by-step: Building in workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.4 Simple filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.5 Document level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.5.1 Step-by-step: Adding security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.6 Applying roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.6.1 Step-by-step: Using roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.7 Deploying and testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Chapter 5. Developing the sample application: Advanced development topics. . . .
5.1 Working with panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 Step-by-step: Creating a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Sub-paneling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 Step-by-step: Creating a comment section using multiple panels . . . . . . . . . . .
5.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 Step-by-step: Adding parameters to the component. . . . . . . . . . . . . . . . . . . . . .
5.4 Advanced filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Step-by-step: Filtering documents that are not older than one week . . . . . . . . .
5.4.2 Step-by-step: Displaying document from a date range defined by user . . . . . . .
5.5 Workplace Collaboration Services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6 Component scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.1 Step-by-step: Creating a component script. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
113
114
114
119
119
126
126
131
131
134
140
142
142
Chapter 6. Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Creating templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1 Step-by-step: Creating a template for your component . . . . . . . . . . . . . . . . . . .
6.3 Template setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.1 Step-by-step: Creating pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.2 Step-by-step: Mapping roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.3 Step-by-step: Creating default parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Using templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4.1 Step-by-step: Adding users that can see the template . . . . . . . . . . . . . . . . . . . .
6.4.2 Step-by-step: Instantiating an application from the template . . . . . . . . . . . . . . .
145
146
146
146
148
148
149
150
152
152
153
Appendix A. Workplace Designer for Domino developers . . . . . . . . . . . . . . . . . . . . . 159
Comparative tables with common Domino Designer functions . . . . . . . . . . . . . . . . . . . . . 160
Appendix B. Application-specific tips and resources . . . . . . . . . . . . . . . . . . . . . . . . . 163
Collaborative development in Workplace Designer 2.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Appendix C. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
iv
IBM Workplace 2.5 Development with Workplace Designer
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
167
167
167
167
167
Contents
v
vi
IBM Workplace 2.5 Development with Workplace Designer
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 on 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 illustrates 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. 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 IBM's application programming interfaces.
Send us your comments in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an email to:
redbook@us.ibm.com
© Copyright International Business Machines Corporation 2005. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.
vii
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYJ Mail Station P099
2455 South Road
Poughkeepsie, New York 12601-5400 U.S.A.
®
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Eserver®
Eserver®
Redbooks (logo)
™
Cloudscape™
Domino Designer®
Domino®
IBM®
Lotus®
Rational®
Redbooks™
Sametime®
WebSphere®
Workplace™
Workplace Managed Client™
The following terms are trademarks of other companies:
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or
both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States,
other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
viii
IBM Workplace 2.5 Development with Workplace Designer
Preface
This IBM® Redpaper provides an overview of the features and functionality of IBM
Workplace™ Designer Version 2.5 and shows application developers how to build
applications for IBM Workplace Collaboration Services V2.5 and IBM Workplace Services
Express V2.5. We introduce a sample status tracking application, and show developers
specific, step-by-step development techniques that they can use to build the component. We
discuss specific design elements in depth and in the context of building the sample
application. We also provide best practices and hints and tips for collaborative development
with Workplace Designer.
The audience for this redpaper is primarily application developers with a background in
Domino® development, Javascript, or other scripting languages.
The team that wrote this Redpaper
This Redpaper was produced by a team of specialists from around the world working at the
International Technical Support Organization, Cambridge, Massachusetts Center.
John Bergland is a project leader at the International Technical Support
Organization (ITSO), Cambridge Center. He manages projects that produce
Redbooks™ about Lotus® Software products. Before joining the ITSO in
2003, John was an advisory IT specialist with IBM Software Services for
Lotus, specializing in Notes and Domino messaging and collaborative
solutions.
Adam Egressy is a consultant IT specialist, working for
AdHoc Systems Ltd., anIBM Business Partner in the Czech Republic. In the
last five years, his work has been focused on Java™ and IBM Lotus Domino
technologies. He often participates in project development and is
responsible for several products developed by AdHoc Systems Ltd. His
areas of expertise include data modeling, object-oriented techniques, XML,
and Web technologies.
Nick Orrick is a staff software engineer and technical
lead with the IBM Lotus support team. His areas of expertise include
LDAP, Web servers, and Java programming. He is a Principal Certified
Lotus Professional for R5 and ND6 in administration and development.
His other certifications include Quickplace and Sametime® administration
and Java 2 programming. Nick received his Bachelor of Computer
Science degree at and is pursuing his Master of Software Engineering
degree at the University of Texas at Austin.
Marc Weinzetl is an accredited IT specialist at the Software Services for
Lotus department of IBM Germany. He joined IBM in 2001 and has over
eight years of experience working with Lotus Software. He is an IBM
Certified Instructor for Notes/Domino R4/R5/R6 for both application
development and system administration. Marc has worked on various
Notes/Domino, Lotus Document Manager, LEI development and
deployment projects over the last several years. Most recently, Marc's focus
has been on IBM Workplace Collaboration Services.
© Copyright IBM Corp. 2005. All rights reserved.
ix
Additional contributors
Thanks to the following people for their contributions to this project:
򐂰 Chris Reckling, Senior Product Manager, IBM Workplace Application Development, IBM
Software Group, Lotus
򐂰 Jane L. Wilson, Knowledge System Architect, IBM Software Group, Lotus
򐂰 Martha Hoyt, Senior Software Development Manager, IBM Software Group, Lotus
򐂰 James Russell, Director, Application Development Tools, Lotus Software, IBM Software
Group, Lotus
򐂰 Salvatore Mazzotta, Senior IT Architect, IBM Software Group, Lotus
򐂰 Whitney Sorenson, Software Engineer, IBM Software Group, Lotus
򐂰 Doochan Han, Software Engineer, IBM Software Group, Lotus
򐂰 Amanda Ricketson, Software Engineer, IBM Software Group, Lotus
򐂰 Michael G. Alexander, Advisory Software Engineer, IBM Software Group, Lotus
򐂰 Marc Hendricks, Domino/Web Server/Support Manager, IBM Software Group, Lotus
򐂰 David Frank, WorkPlace API Toolkit Test, IBM Software Group, Lotus
Become a published author
Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with
specific products or solutions, while getting hands-on experience with leading-edge
technologies. You'll team with IBM technical professionals, Business Partners and/or
customers.
Your efforts will help increase product acceptance and customer satisfaction. As a bonus,
you'll 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
Redpaper or other Redbooks in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an email to:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYJ Mail Station P099
2455 South Road
Poughkeepsie, New York 12601-5400
x
IBM Workplace 2.5 Development with Workplace Designer
1
Chapter 1.
Introduction to IBM Workplace
Designer Version 2.5
IBM Workplace Designer Version 2.5 is an intuitive visual development tool that allows
application developers, designers, and others to easily create and deploy components for the
IBM Workplace environment. Workplace Designer V2.5 features a visual design interface and
powerful scripting capabilities that are familiar to Domino application developers and are
intuitive for Microsoft® Visual Basic developers and other script developers. It is based on
Eclipse, supports a service-oriented architecture (SOA), and incorporates the following
industry standards:
򐂰
򐂰
򐂰
򐂰
XML for data access and exchange
Java 2 Enterprise Edition (J2EE)
HTML/CSS for portal development
JavaScript for the programming language
Workplace Designer is ideal for organizations of all sizes, providing a natural path for
businesses that have invested in Domino and Visual Basic development skills and that have
chosen Workplace to extend their investments. Domino developers can use existing skills,
intuitive forms and views, and the JavaScript visual environment to build document-oriented,
business process applications much more quickly and at a lower cost than other J2EE tools.
Workplace Designer is flexible and robust, providing a tool that is suitable for all levels of
expertise. Visual Basic users are likely to find the Workplace Designer form-based interface
easy to use, with user interface (UI) controls that they can drag and a standard scripting
language. Advanced developers can take advantage of the extensibility of Workplace
Designer to integrate with Java-based tools, while less experienced developers with no
knowledge of Java can create full-featured programs with a familiar script interface.
Workplace Designer is ideal for composite application development and for extending existing
applications with collaborative components.
This Redpaper provides an overview of the features and functionality of Workplace Designer
V2.5 and shows application developers how to build applications for IBM Workplace
Collaboration Services V2.5 and IBM Workplace Services Express V2.5. We introduce a
sample status tracking application and show you specific, step-by-step development
techniques that you can use to build the component. We discuss specific design elements in
© Copyright IBM Corp. 2005. All rights reserved.
1
depth and in the context of building the sample application and provide best practices, hints,
and tips around collaborative development with Workplace Designer.
The audience for this Redpaper is primarily application developers with a background in Java,
Domino development, Javascript, or other visual scripting languages.
This chapter covers the following topics:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
2
1.1, “Overview” on page 3
1.2, “Business value and key advantages” on page 5
1.3, “Developer audience for Workplace Designer” on page 5
1.4, “Overview of tools for customizing Workplace applications” on page 6
1.5, “Positioning between Workplace Designer and Application Template Editor” on page 6
1.6, “Introduction to the sample application” on page 12
1.7, “Approach used to develop the application” on page 13
IBM Workplace 2.5 Development with Workplace Designer
1.1 Overview
In many corporations, a business software platform is only as useful as the applications that
you can develop with it. With that in mind, IBM has developed Workplace Designer V2.5, a
standards-based development tool that allows developers to quickly and easily create
components for release 2.5 of the Workplace family of products. These components can then
be used within Workplace applications from any Web browser.
Workplace Designer V2.5 is a visual script development environment for building application
components for IBM Workplace Collaboration Services V2.5.1 and IBM Workplace Services
Express V2.5. The composite applications that run in the Workplace environment can be
enhanced by components that are created on and deployed from Workplace Designer V2.5.
The intuitive visual user interface, the powerful scripting capabilities, and the simplified
component deployment make Workplace Designer V2.5 the fastest and easiest way to create
and deploy new components for Workplace applications. Figure 1-1 illustrates the user
interface for Workplace Designer.
Component Navigator
Component Canvas
Properties panel
UI Controls
Data navigator
Figure 1-1 Overview of the Workplace Designer user interface
Chapter 1. Introduction to IBM Workplace Designer Version 2.5
3
Workplace Designer, which is based on the open-source Eclipse 3.0 platform, is completely
integrated with Workplace Collaboration Services V2.5 and Workplace Services Express
V2.5. It installs on top of the IBM Workplace Managed Client™. Workplace Designer includes
a developer license for Workplace Collaboration Services 2.5 and IBM WebSphere® Portal
and can seamlessly deploy components to the server for testing and assembly into templates
and applications. You can authenticate with the Workplace server and launch the tool from
the Workplace client. You can use the components in conjunction with the application
template editor.
1.1.1 Workplace Designer features
Workplace Designer V2.5 includes the following features:
򐂰 Components: These collections of forms, schemas, scripts, and images comprise a
single portlet in the Workplace server.
򐂰 Design elements: These parts of Workplace Designer let you create and modify
components visually.
򐂰 Form editor: This provides the component user interface. Forms are critical elements of a
collaborative system, providing a flexible way to collect and process information. They are
the main user interface element and contain the controls that comprise the application
interface. You can use forms to create, edit, and display data stored in documents.
򐂰 UI control palette: This palette provides all available UI controls. UI controls are visual
elements that allow users to work with data for a form. UI controls include edit fields,
buttons, selection lists, and links.
򐂰 Events: Events provide full programming capabilities, such as a button click or field action,
document open or close, and so on.
򐂰 Scripting with full JavaScript interfaces to built-in functions: This includes a script
editor that offers many of the features found in the Eclipse script editor, including syntax
coloring and content assist.
򐂰 Easy deployment options: These are provided for testing and production scenarios.
These features are discussed in more detail in the subsequent chapters of this paper.
The following characteristics describe the benefits of using Workplace Designer:
򐂰 Familiar design paradigm: A form designer allows you to create the presentation layer of
the component. With forms, you can enter, display, and process information through fields,
views, buttons, and other UI controls.
򐂰 Full programming support: Events support programming capabilities. Events include
button onClick, field onChange, form onSubmit, and others to support the event-driven
programming model.
򐂰 Powerful script capabilities: Scripting is handled by JavaScript and JavaScript interfaces
to built-in functions. A script editor with syntax coloring and code assist features speeds
development. There is also a complete API available to access documents.
򐂰 Productivity enhancers: Simple actions added to a form perform specific commands.
򐂰 Visual tools palette: A Widget palette allows the developer to drag controls into the form.
򐂰 Part of the IBM Rational® Software Development Platform: This platform is a complete
solution for developing software and software-based systems. From requirements to
design to test, you can use Workplace Designer with the entire platform.
򐂰 Easy to start and run: Workplace Designer has easy deployment options for component
testing and production scenarios.
4
IBM Workplace 2.5 Development with Workplace Designer
1.2 Business value and key advantages
Workplace Designer V2.5 provides business value in the following ways:
򐂰 The easy-to-use, high-level, intuitive visual development environment requires less
training for your developers. Workplace Designer V2.5 features a UI that is familiar to
Domino application designers but is intuitive to Visual Basic and other script developers.
򐂰 You can automate existing business processes through forms-based development.
Workplace applications facilitate security-rich, role-based, document-oriented, business
process applications. Workplace Designer V2.5 makes it possible to quickly create and roll
out components that build applications that automate typical enterprise processes, such
as expense reports, change requests, or project management.
򐂰 Support for the robust security and administration features of Workplace applications
allows role-based access to components. Every Workplace application makes use of roles
to manage component access and permissions, allowing system administrators control
over the functions available to other users.
򐂰 JavaScript, XML, and a document API allow your development staff to leverage their
existing skill sets. The Workplace Designer script editor provides syntax highlighting,
content assist, and other features to make the component developer more productive.
򐂰 The deployment and distribution of components to the Workplace platform are simplified.
Typical deployment of a component to a J2EE application server is a complex process with
multiple steps. Workplace Designer V2.5 simplifies this process for the developer. Profiles
in Workplace Designer enable developers to specify deployment options so that the same
component can be deployed quickly to different servers. Components, WAR, and Data
Description Library (DDL) files can also be exported from Workplace Designer for
distribution to a production server.
򐂰 The importing of existing Domino forms to create components is supported. Workplace
Designer supports the import of Domino forms from existing applications. This gives
Domino developers a starting point for development of Workplace applications.
Workplace Designer provides the fastest mechanism for creating and deploying components
to the Workplace platform. It does not require J2EE development skills and script developers
can readily use it.
1.3 Developer audience for Workplace Designer
Workplace Designer allows developers to build a Workplace component in the constructs they
are accustomed to. For example, Workplace Designer incorporates design elements such as
forms, views, edit boxes, buttons, and scripts. Workplace Designer is targeted to a broad
range of developmental skills: from users without a great deal of experience with development
platforms that wish to quickly build and deploy applications using intuitive visual development
environment to users with extensive programming backgrounds in Domino development,
Java, and Visual Basic or similar scripting languages.
Chapter 1. Introduction to IBM Workplace Designer Version 2.5
5
Note: Workplace Designer is intended for developers with a broad range of skills and
development backgrounds. Ultimately, it is intended for developers and IBM Business
Partners who want a fast and efficient way to develop components for the Workplace
environment. Backgrounds that are especially suited for Workplace designer include:
򐂰
򐂰
򐂰
򐂰
򐂰
Developers with Domino Designer® experience
Developers with Visual basic or other scripting environment experience
IBM WebSphere Portal/portlet developers,
JavaScript developers
Java developers
1.4 Overview of tools for customizing Workplace applications
Tools that you can use to develop and customize Workplace applications range from the
browser-based application template editor tool to the IBM Rational Application Developer 6
integrated development environment. The tools you use depend on what you are trying to do
and what level of customization you need. In this section, we highlight the complementary
functionality of Workplace Designer and Workplace Application Template Editor.
The available tools are:
򐂰 Workplace Designer: Use this tool to create document-oriented collaborative components
and applications for the Workplace environment quickly with visual tools and JavaScript.
򐂰 Workplace Application Template Editor for Templates, Forms: Use this tool to create
reusable templates in the browser, either application templates or form templates.
򐂰 Workplace data access tool: Use this tool to create simple database applications either
locally or in the Workplace Managed Client.
򐂰 Workplace Collaboration Services API Toolkit: Use this set of Java APIs and Web services
with IBM Rational Application Developer to create and access Workplace Collaboration
Services and Workplace Managed Client applications.
򐂰 IBM Rational Application Developer 6: Use this tool to build portlets and other business
logic that can be used to integrate with Lotus Domino and other systems. Use to create
rich client applications by building Eclipse plug-ins.
1.5 Positioning between Workplace Designer and Application
Template Editor
As we discuss the functionality of Workplace Designer, it is important for you to understand
the role and function of the Workplace Application Template Editor (formerly known as
Workplace Builder), and how it is used to build upon components created with Workplace
Designer.
At the core of the Workplace concept is an architecture and application platform that connects
collaboration activities to the collaboration participants. As an application platform, Workplace
centers on the ability to build custom components, templates, and applications and on tools
such as the Workplace Application Template Editor. The primary tools for building the
components and applications include Workplace Designer and Application Template Editor.
The functionality of each tool is addressed in 1.5.1, “Workplace Designer and Workplace
Application Template Editor: What is the difference?” on page 7.
6
IBM Workplace 2.5 Development with Workplace Designer
Note: While this section describes key terminology and functionality within Workplace
Application Template Editor, Chapter 6, “Templates” on page 145 provides actual hands-on
steps for using Workplace Application Template Editor to create a template from the
component, and eventually deploy the application from the template.
1.5.1 Workplace Designer and Workplace Application Template Editor: What is
the difference?
The difference between Workplace Designer and Workplace Application Template Editor is as
follows:
򐂰 Workplace Designer is the tool for easily creating and deploying components in the
Workplace environment.
򐂰 Workplace Application Template Editor is an application assembly tool that allows
business users to rapidly assemble components into applications, based upon a template.
A template is the glue that binds multiple components into a Workplace application.
Applications are the things that people interact with as they conduct their business
processes.
Note: To learn more about the specifics of using Workplace Application Template
Editor, see Building a Component for IBM Workplace, REDP-3952:
http://www.redbooks.ibm.com/abstracts/redp3952.html?Open
Figure 1-2 on page 8 is a conceptual view of how Workplace Designer is used to design core
components, while Workplace Application Template Editor is used for creating, managing,
editing, and deploying templates.
Chapter 1. Introduction to IBM Workplace Designer Version 2.5
7
Portal Page
Portlet 1
Portlet 2
Using Workplace Designer to
create components
Workplace
Designer
Component
Template - Built by Application Template Editor
Portal Page
Portlet 2
Parameter
es
in
ef
Roles
D
Using Application Template Editor to
create and manage Templates
Portlet 1
Portlet 1
Figure 1-2 Overview of relationship between Workplace Designer and Workplace Application Template Editor
1.5.2 Terminology of key concepts for Workplace applications
So that you can better understand the architecture in a Workplace application and the role of
Workplace Designer, you need a foundation for the terminology. The key terms include:
򐂰
򐂰
򐂰
򐂰
Component
Templates
Roles and membership
Applications
Components, templates, and applications
A Workplace application is made up of Workplace components. Workplace Collaboration
Services includes many Workplace components, such as Discussion, Team Calendar, Team
Task List, Contact List, Forms, Document Library, Search, and People Finder. As this paper
demonstrates, you can also develop and deploy your own Workplace components to an
application.
Tip: You can think of a component in terms of an equation:
Component = Portlet + Roles and Parameters + Data Management
8
IBM Workplace 2.5 Development with Workplace Designer
A Template is a reusable structure or configuration that connects a specific UI layout with
options, settings, and roles. The properties and use of templates are key aspects of
Workplace application development. In brief, a template is a pre-made configuration that is
both reusable and customizable.
Figure 1-3 illustrates the relationship between components, templates, and applications.
Application Life Cycle
Components are built by a developer
A portlet in the UI
Assembled into a template using template editor
Figure 1-3 Application life cycle: the relationship between components, templates, and applications
Hypothetically, we could deploy a component (portlet) to a portal page and have a Workplace
application (see Figure 1-2 on page 8). However, the component can only work in a personal
portal page, which limits the capability of the component to collaborate with others. With
Workplace Application Template Editor, you now have the ability to make your components
and applications in templates. A template defines the Workplace application, its pages, and
the application components that are deployed on each page. In this way, you can provide a
pre-configured set of portlets and pages for a specific business task.
Templates have the distinct advantage of being able to be modified by administrators and
other users. Administrators can also control the deployment with user roles and other
administrative features. Figure 1-4 shows an overview of the template development process.
Figure 1-4 Workplace template construction
To work with a template, you must have access to the Workplace Application Template Editor,
the tool for viewing and editing templates. To learn more about the specifics of using the
Workplace Application Template Editor, see Building a Component for IBM Workplace (TM),
REDP-3952:
http://www.redbooks.ibm.com/abstracts/redp3952.html?Open
Chapter 1. Introduction to IBM Workplace Designer Version 2.5
9
Figure 1-5 illustrates the relationship between templates, applications, components, and
Workplace Application Template Editor. In the standard scenario, Workplace Application
Template Editor is used to create a new template either from scratch or from an existing
template. You can select Workplace components or simple portlets from the Workplace
Solutions Catalog and add them to the current template. You can find the catalog at:
http://catalog.lotus.com/wps/portal/portalworkplace
Workplace
Component
(portlet)
Catalog
Select
Components
(portlets)
creates
Application
Template
IBM Workplace
Editor
Builder
designs
Template
(XML File)
IBM Workplace
Application
feed
Instantiation
Service
creates
Figure 1-5 The relationship templates, application, components, and Workplace Application Template
Editor
The Workplace Application Template Editor also allows you to edit existing application
instances. For authorized users, the Workplace browser UI renders an Edit button in
application instances. With this button, you can edit the current application in the Application
Template Editor. You can alter the application as you use it or save it as a new template.
This feature allows simple iterative development of new templates. Starting with a simple
template and a single application instance, you can test the application and apply any
required customization to the running instance. After the application fulfills all business
requirements, you can save it as a new template. As a template, you can provision the same
functionality to other teams or workgroups over and over again. This ability for re-use
highlights the value of templates in the Workplace application development process.
Roles and membership
Workplace components can define roles for content. A role grants access to a set of actions
or commands that apply to the content. For example, a discussion forum might have the
following roles:
򐂰 Reader: Able to read postings
򐂰 Author: Able to create postings
򐂰 Moderator: Able to delete postings
In a Workplace application, the application roles are defined in the context of the business
process. They can be named anything that the application designer wants, for example:
򐂰
򐂰
򐂰
򐂰
10
Project Manager
Team Leader
Team Member
Project Reviewer
IBM Workplace 2.5 Development with Workplace Designer
Application roles must be mapped to component roles. This mapping ultimately determines
what access a user receives when assigned to an application role. For example, Project
Manager would be mapped to Moderator in a discussion forum. Application roles are mapped
to Workplace component roles in the Workplace Application Template Editor.
Building upon roles, each Workplace has membership. Membership is defined by the
individuals and groups who are assigned roles that determine their access to the application.
The names of Workplace members appear in the Members portlet displayed in every
application. Generally, application managers are Moderators, and application users are
Contributors or any other role you want to define.
Roles and the ability to access templates
Permission to work with Workplace templates is determined by user policies and assigned
template roles:
򐂰 User policies provide permission at the most fundamental level for users to work with
templates and applications. Workplace administrators set user policies.
򐂰 Template roles provide permission to edit or use templates. Template roles are assigned to
users by template owners.
Applications
All Workplace applications are based on a template. When customizing an application, you
can choose either to modify the existing application or to modify the template on which that
application is based.
For example, suppose you want to add your own component to an existing Team Space.
Furthermore, you want to have that modification appear for all future Team Spaces. You have
two choices:
򐂰 Modify the template by adding your component.
򐂰 Save an existing application as a template. This concept is very similar to Lotus
Quickplace.
Table 1-1 lists the Workplace applications that can be created using the templates provided
with Workplace Collaboration Services.
Table 1-1 Applications created from templates
Workplace application
Description
Team Space
Participate in discussions and chats,
share documents and a team calendar,
and search for information related to a
project
Discussion
Participate in threaded discussion forums
with teams
Chat Room
Communicate with team members, view
archives of chat transcripts, and see a list
of chat participants
Domino Application
Access HTML-enabled Domino
applications
Document Library
Manage document versions, approvals
Chapter 1. Introduction to IBM Workplace Designer Version 2.5
11
1.6 Introduction to the sample application
Most of this Redpaper is based upon a sample scenario application that shows how to
actually build and deploy a workplace component in greater detail. The sample application is
a status reporting application that tracks summaries, tasks, and expenses related to an
activity. To keep the application specifically generic, and applicable to a broad range of uses,
we have used the term activity. Keep in mind that the activity could be a project, a goal, or a
milestone which has tasks affiliated with it.
Note: All sample code used for building this application can be downloaded from the
following URL:
ftp://www.redbooks.ibm.com/redbooks/REDP4090/
1.6.1 Sample application overview
The Status Reporting application allows users and managers to record and track the status of
activities, tasks, and expenses related to specific tasks.
The sample application has been written for two sets of users, based on their roles and
underlying business needs:
򐂰 Users
Users can create and submit their status reports. Once a status report has been created,
users can save it in a draft mode, which allows them to edit it at a later time, or submit it.
򐂰 Managers
Managers can perform two key tasks:
– They can view current status reports that have been submitted and provide comments.
– They can manage categories (add, edit, and delete) used for grouping tasks.
Figure 1-6 illustrates a conceptual overview of the status reporting application.
U sers view of S tatus R eports
U ser S tatus R eport
D raft
Sum m ary of
accom plishm ents
C urrent
Tasks
A rchived
Expenses
M anagers view of S tatus R eports
A ll
O lder than 1 w eek
Figure 1-6 Conceptual overview of status reporting application
12
IBM Workplace 2.5 Development with Workplace Designer
H istory / Sum m ary from
previous week
Note: 2.4.2, “Sample scenario: Application details” on page 26 describes the functionality
of the application in greater detail.
1.7 Approach used to develop the application
In this paper, we provide an overview of Workplace Designer, discuss its features and
functionality, then provide the reader with a detailed approach to building a sample
application. In the chapters dedicated to building the application (Chapters 3, 4, and 5), we
took the approach to first begin with basic functionality and then introduce more advanced
features and functionality in subsequent chapters. This paper has the following structure:
򐂰 This chapter introduces Workplace Designer 2.5, discusses its business value, clarifies
specific terminology around Workplace components, and provides a brief introduction to
the sample application.
򐂰 Chapter 2, “Features and functionality” on page 15 provides an overview of the features
and functionality provided within Workplace Designer 2.5. It begins with an initial overview
of the design elements and discusses how to set up and begin working with Workplace
Designer. Then, we introduce the sample application that is developed throughout the
subsequent chapters of this Redpaper.
򐂰 Chapter 3, “Developing the sample application: Basic development topics” on page 29
establishes the basic foundation for the application by describing how to build the core
design elements. It is an excellent starting point for developers that are new to the
concepts and design elements of Workplace Designer 2.5.
򐂰 Chapter 4, “Developing the sample application: Intermediate development topics” on
page 73 is considered the “intermediate” chapter: It shows developers how to build in
more advanced functionality, which includes adding response documents, creating the
task forms, using dynamic combo boxes, embedding views into forms, and others.
򐂰 Chapter 5, “Developing the sample application: Advanced development topics” on
page 113 proceeds into the advanced functionality, discussing working with Panels and
subpanels, and introduces the Workplace Collaboration Services API.
򐂰 Chapter 6, “Templates” on page 145 discusses how to deploy the component as a
template and an application in Workplace Collaboration Services 2.5.
Chapter 1. Introduction to IBM Workplace Designer Version 2.5
13
14
IBM Workplace 2.5 Development with Workplace Designer
2
Chapter 2.
Features and functionality
This chapter provides an overview of the features and functionality of Workplace Designer
2.5. It begins with an initial overview of the design elements and discusses how to set up and
begin working with Workplace Designer. Finally, this chapter introduces the sample
application that is developed throughout the subsequent chapters of this Redpaper.
© Copyright IBM Corp. 2005. All rights reserved.
15
2.1 Overview of features in Workplace Designer
Workplace Designer 2.5 includes the following features:
򐂰 Components: These are collections of forms, schemas, scripts, and images that
comprise a single portlet in the Workplace server.
򐂰 Design elements: These are parts of Workplace Designer that let you create and modify
components visually.
򐂰 Form editor: This is the component user interface (UI). Forms are critical elements of a
collaborative system that provide a flexible way to collect and process information. They
are the main user interface elements and contain the controls that comprise the interface
of the application. Forms are used to create, edit, and display data stored in documents.
򐂰 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.
򐂰 Events: These provide full programming capabilities, such as a button click or field event,
document open or close event, and so on.
򐂰 Scripting: This provides full JavaScript interfaces to built-in functions. This includes a
script editor that offers many of the features found in the Eclipse script editor, including
syntax coloring and content assist.
򐂰 Easy deployment options: These are provided for testing and production scenarios.
The Workplace Designer features are discussed in more detail throughout the following
sections of this chapter. Additionally, subsequent chapters provide much greater detail about
how to use these different design elements. You have ample opportunity to use each design
element while building the 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.
2.2 Overview of design elements
The Workplace Designer design elements are components, forms, UI controls, and events.
2.2.1 Components
Workplace Designer components are sets of forms, scripts, and other elements from which
you construct portlets. (Workplace applications consist of one or several portlets.) You can
use Workplace Designer to build components, deploy them in the Workplace server as
portlets, and add them to Workplace applications. These applications are then available to
Web users.
You can create new components from scratch or you can import an existing Domino database
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.
Note: The term component is sometimes referred to as a portlet. This is because the
component that you create with Workplace Designer is deployed as a portlet to a
Workplace server.
16
IBM Workplace 2.5 Development with Workplace Designer
Figure 2-1 Creating a new component
Workplace Designer components support the role-based security model of Workplace
applications. After you have deployed the component and added the component to an
application or application template, you can set access to components by mapping
component roles to the roles in that specific Workplace application. For example, if you map
the template role Contributor to the component role Reader, users with Contributor access to
the application then have Reader access to the component.
Workplace Designer provides a method for easily deploying components to the Workplace
server that is to be used in Workplace applications. This involves creating a deployment
profile in Workplace Designer.
2.2.2 Forms
A Workplace Designer form is the primary user interface for interacting with Workplace
components. Forms in the component allow users to input and display information. A
component might have numerous forms. To allow the component user to navigate from form
to form in the current component, the component developer can leverage the form properties
or use UI controls.
The form is the central design element in Workplace Designer.
Tip: For developers who are skilled in Notes/Domino application development, there are
many different stand-alone design elements, including views, agents, and so on.
Workplace Designer has one basic element, the form. To create a view, you must embed it
in a form; to run the Workplace equivalent of a Notes/Domino agent, you must make it an
event in the form, and so on. In addition, Notes/Domino defines data as part of the form
design. Workplace Designer defines data in separate schemas, then the developer binds
the UI controls to the schema elements. If you do not have an existing schema during form
design, Workplace Designer can build the schema for you as you specify the data binding
for the UI controls.
Note: You must create a component before you can create a form.
Chapter 2. Features and functionality
17
Workplace Designer offers several different ways for you to create a new form. You can start
with a blank form, import a form from a Domino database, or copy an existing form. When you
create a new, blank form, you are prompted for the name of the form, a comment, and
whether to:
򐂰 Create a schema for this form
򐂰 Use an existing schema
򐂰 Not use a schema
Figure 2-2 Creating a new form using the form editor
To create, view, and edit forms, Workplace Designer includes the Form editor (Figure 2-3 on
page 19). You can use this graphical editor to arrange artifacts such as UI controls, buttons,
graphics, and so on. These elements are added using the UI control palette (described in the
following section). You can then drag these components into the form.
Workplace Designer lets you perform data validation at several levels. Field level validation is
related to field type and allowed values. Document level validation happens when multiple
fields are involved in the validation process. Depending on the type of validation, it can occur
in the client prior to submitting the data, or in the server prior to updating the back-end
document.
2.2.3 UI controls
An important concept in Workplace Designer development is the UI control. These are
graphical elements (for instance, a button or link) that users can interact with. Workplace
Designer offers a large set of UI controls that you can add to your forms. These include:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
18
Edit box
Multi-line edit box
Button, list box
Combo box
Check box
Radio button
Link
Computed field
Image
IBM Workplace 2.5 Development with Workplace Designer
These UI controls are accessible through the UI control palette (Figure 2-3), located in the
upper-right section of the Form editor interface.
Figure 2-3 UI Control palette
View controls
Views are UI controls that can be added to a form to display a collection of documents. In
Workplace Designer, views are controlled through forms. To create a view, you must insert a
view control into a form and then associate one or more schemas and individual fields to the
view. View controls provide a means of separating the presentation of the view from the data
that eventually populates it. After inserting a view control into a form, you can modify the
format of the control, similar to any other UI control, using styles or custom formatting
properties.
Note: For developers skilled in Notes/ Domino application development, one area in which
Workplace Designer differs from Domino Designer is how it handles views.
A view is a basic database object that displays a list of documents from the database. A visual
representation of a view is usually a table, where each column displays a different type of
information and each row belongs to one specific document.
Views are designed to effectively select a subset of documents that have something in
common. For example, we often want to display documents that were created using a certain
schema.
Another typical characteristic of views is that they can be sorted by values in one or more
columns. For example, in a view of a corporate phone directory, we can sort the employees by
their last names.
Chapter 2. Features and functionality
19
Container controls
A container control (as the name implies) is a UI control that can contain other UI controls.
There are three types of container controls:
򐂰 Panel: A panel is a rectangular area in a form to which you can add core controls. Panels
can also be used to refer to other documents and to repeat a selected XML node.
򐂰 Table: A table contains individual cells. You can add controls into the table cells.
򐂰 View: A view is a rectangular section on the form that contains rows and columns of data
extracted from XML, based on a defined query.
2.2.4 Events
A vital part of any development environment is event handling. Workplace Designer supports
several types of event controls, including:
򐂰 UI control events: Each UI control can have a set of client-side events. For example, a
button can produce an “on click” event. The code can be executed at either the server side
or the client side.
򐂰 Component events: These are standard Workplace Collaboration Services events; for
example, when a component is instantiated or when a member is added or removed to the
Workplace application. These events are defined and handled at the component level,
using a set of event global properties.
Note: A fix must be applied to the server for this to work.
򐂰 Form and document events: Form events support events in edit controls, such as open,
close, unsafe, apostasies, and so on. Document events support the same events as form
events.
2.3 Setting up the development environment
To work with Workplace Designer, you must have a Workplace Collaboration Services server
or a Workplace Services Express server environment. If you do not already have a server,
Workplace Designer provides the Workplace Collaboration Services server, which is licensed
for test purposes only.
There are two parts to Workplace Designer: the tool and the runtime files:
򐂰 The Workplace Designer runtime files must be installed in an existing Workplace
Collaboration Services 2.5.1 server or Workplace Services Express 2.5 server.
򐂰 The Workplace Designer tool must be installed on the same computer as the IBM
Workplace Managed Client.
This section describes the basic steps for setting up a basic development environment.
20
IBM Workplace 2.5 Development with Workplace Designer
Important: This section provides an overview of the installation steps. For complete
documentation on installing Workplace Designer, refer to the IBM Workplace Designer 2.5
Installation Guide at:
http://www-128.ibm.com/developerworks/workplace/documentation/designer/
You can also access the Workplace Designer 2.5 Installation Guide as an Additional
Material for this paper. See Appendix C, “Additional material” on page 165 for detailed
instructions on accessing the FTP site.
2.3.1 Basic installation steps
The basic installation steps are:
1. Install the Workplace Collaboration Services (V2.5.1) or Workplace Services Express
server. Follow the steps for a demo server, so that you use the Cloudscape™ database
server and the WebSphere Member Manager. Of the products to choose during install,
while you can do them all, you only need the Messaging, Collaboration Services, and
Workplace Managed Client.
Attention: For complete information about installing and configuring a Workplace
Collaboration Services 2.5 server, please see the IBM Workplace Collaboration
Services: Release 2.5 Deployment Guide, SG24-6777:
http://www.redbooks.ibm.com/redpieces/abstracts/sg246777.html?Open
2. After Workplace Collaboration Server is installed, you must install the Rich Client
provisioning server. For details on how to do this, please refer to the Workplace
Collaboration Services 2.5.1 Info Center:
http://publib.boulder.ibm.com/infocenter/lwpphelp/index.jsp?
The information that you need is in the section called Installing and configuring the
provisioning server.
Tip: For our test servers, we did not create site certificates; however, you should make
sure that you set the user policy to allow users to obtain the rich client.
3. From this point onward, refer to the IBM Workplace Designer 2.5 Installation Guide and
Release Notes available at:
http://www-128.ibm.com/developerworks/workplace/documentation.html
4. Install the Designer Runtime server files on the Workplace Collaboration Services (v.
2.5.1) server.
5. Install the Workplace Managed Client on the client workstation from the Workplace Web
site using the Workplace Managed Client URL (Figure 2-4).
Figure 2-4 Link to download the rich client from a Workplace Collaboration Services server
6. After you have successfully installed the Workplace Managed Client, you must install the
Workplace Designer Client (Tool portion) on top of the Workplace Managed Client.
Chapter 2. Features and functionality
21
When the Workplace Designer has been successfully installed, a Workplace Designer icon
becomes part of your desktop, and you can launch Workplace Designer with this icon:
As Workplace Designer launches, an introductory page opens. From this page, you can either
create a new component, or work with an existing component (Figure 2-5).
Figure 2-5 Introduction screen for Workplace Designer
Tip: Reduce the initial memory size of the server by reducing the portal server minimum
size to 200 MB, and by changing the VM heap for the mail server to 200 MB. Change the
startNetworkServer.bat to start the Cloudscape server with a minimum of 128 MB.
Tip: Increase the portal timeout so that you do not have to keep logging in to a test server.
2.4 Sample application: Status reporting component
The remainder of this Redpaper describes how to build and deploy a Workplace component
in greater detail. To facilitate this discussion, a sample status reporting application is used
throughout the book to provide examples of how to implement each technique. This sample
application is available for download from the IBM Redbooks Web site. For information about
how to download this software, see Appendix C, “Additional material” on page 165.
22
IBM Workplace 2.5 Development with Workplace Designer
Note: All sample code used for building this application can be downloaded from the
following URL:
ftp://www.redbooks.ibm.com/redbooks/REDP4090/
2.4.1 Sample application overview
The status reporting application allows users and managers to record and track the status of
activities, tasks, and expenses related to specific tasks.
The sample application has been written for two sets of users:
򐂰 Users
Users can create and submit their status reports. After a status report has been created, a
user can save it in a draft mode, which allows them to edit it at a later time, or they can
submit it.
򐂰 Managers
Managers can perform two key tasks:
– They can view current status reports that have been submitted and provide comments.
– They can manage categories (add, edit, and delete) used for grouping tasks.
Note: 2.4.3, “Use cases” on page 27 describes the functionality of the application in
greater detail.
Figure 2-6 illustrates the initial view of status reports that users see when they first log in to
the system. From this view, a user can either create a new status report or view an existing
report.
User view of status reports
Draft reports
Current reports
Archived reports
Figure 2-6 User’s view of existing status reports
Chapter 2. Features and functionality
23
Figure 2-7 illustrates the actual status report form. Users fill out information about the activity
that they are working on and add details about specific tasks and any expenses related to the
activity. After the users have provided the information, they can either submit the status report
or save it as a draft.
11/23/05
Figure 2-7 Overview of the status reporting component: User creating a new status report
From the manager’s perspective, the manager is notified by e-mail when a user submits the
status report (see Figure 2-8 on page 25).
24
IBM Workplace 2.5 Development with Workplace Designer
Figure 2-8 Mail notifications for each submitted status report
When a manager logs in to the status report application, the manager can see an overview of
reports that have been submitted and those that have not been updated within the last week.
Manager can see all reports
Reports that have not been updated within the last week
Figure 2-9 Manager’s view of status reports that were submitted by users
Chapter 2. Features and functionality
25
2.4.2 Sample scenario: Application details
This section describes the characteristics and functionality of the application. We describe the
relationships between documents, the primary user roles, typical use cases, and the technical
functionality to be included in the application.
Relationships
In the status reporting sample application, status reports are related to an activity. (The IBM
team kept this at an intentionally high level, and somewhat generic, so that this can be applied
to a project, a goal, a milestone, and so on). A status report consists of an activity and can
have tasks, expenses, and comments.
Status Report
Activity
Task(s)
Expense(s)
Comments to Report
Figure 2-10 Relationship of sections that make up a status report form
User roles
The application is designed for two types of users: users and managers. Table 2-1 shows the
functionality included for each user role.
Table 2-1 User roles
26
User type
Access rights
User
User can access the system and create a
new status report, then save it as a draft,
submit it, or archive the report. User can
edit an existing status report that is still in
draft mode.
After a status report has been submitted
and is in the current state, then the user
can only provide comments to the original
report.
Manager
Manager can view all current reports, and
comment on current reports, but can only
view archived reports.
IBM Workplace 2.5 Development with Workplace Designer
2.4.3 Use cases
Table 2-2 summarizes the ways in which users interact with the system.
Table 2-2 Use cases for the user role
Activity
Use case
User creates new Status Report.
User logs into application.
User clicks New Draft button.
User completes information in the Status
Report form.
User saves as draft, or submits status
report.
User edits a current status report.
User navigates to status report in the draft
state.
User opens report and edits report.
User can save as draft, or submit report to
manager.
Note: User can only edit reports in the
current state.
User creates a new status report based on
an existing status report.
User opens an existing status report.
User clicks Update button.
System generates new status report and
includes the summary from the existing
status report.
User creates a new task.
From within Status Report, user clicks
New Task button.
System generates new task.
User provides details of task.
User creates an expense.
From within Status Report, user clicks
New Task button.
User changes state of report from Draft
status to Current status.
User creates or opens a report in draft
status.
User clicks Submit Report button.
System changes report status to Current.
Manager is notified by e-mail that report
has been submitted.
User changes state of report from Current
status to Archived status.
User opens a report in current status.
User clicks Archive button.
System changes report status to archived.
Managers have a super-set of the rights given to users. Table 2-3 summarizes the additional
rights that managers have to the system.
Table 2-3 Use cases for the Manager role
Activity
Use case
Manager views submitted reports.
Managers can only view reports in the
current state.
Manager enters comments on a status
report.
Manager opens and views a current
report.
Manager enters comment on report.
Manager saves report.
Chapter 2. Features and functionality
27
28
Activity
Use case
Manager filters view of submitted reports.
Manager enters or modifies dates within
the Display Reports form fields, then clicks
Search button.
System shows reports that meet criteria of
display dates.
Manager uses managing task categories.
Manager clicks Manage Task Category
button.
System displays existing categories and
subcategories.
Manager can 1) add new category, 2)
delete a category, or 3) edit an existing
category.
If manager chooses new category,
manager also must provide appropriate
subcategory information.
IBM Workplace 2.5 Development with Workplace Designer
3
Chapter 3.
Developing the sample
application: Basic development
topics
In this chapter, we provide the steps that are required to build a basic Workplace component
that can be deployed and used in a Workplace Collaboration Services server.
This chapter makes use of the following technologies:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Component
Schemas
Forms
Views
Buttons
Using Visible properties
Script Libraries
Validation
© Copyright IBM Corp. 2005. All rights reserved.
29
3.1 Creating a Workplace component
Workplace Designer provides the ability to create components that support human
collaborative activities. Generally, a component is a form-based, document-centric element in
a composite application. Deploying a component means moving it from the Workplace
Designer environment to a Workplace Collaboration Services environment as a portlet and
creating the persistent data store for the component data.
Note: The term component is sometimes referred to as a portlet. This is because the
component that you create with Workplace Designer is deployed as a portlet to a
Workplace server.
Note that Workplace Designer applications are not self-contained. In the Workplace model,
you must deploy components to the Workplace server where they are to be run, and then
perform additional setup to include the component in one or more Workplace composite
applications.
Workplace Designer components are sets of forms, schemas, scripts, and other elements
from which you construct portlets. After deployment, one component comprises a single
portlet on the Workplace server. Workplace Designer offers you two ways to create a new
component. First, you can build a new component from scratch. Second, you can import an
existing Domino database as a starting point.
When you create a component based on a Lotus Domino database, Workplace Designer
converts Lotus Domino database design elements into Workplace Designer design elements.
For example, if the Lotus Domino database contains three forms, the component created
from it also contains three forms. Workplace Designer also creates schemas for components
created from Lotus Domino databases based on the fields in the Domino forms. Figure 3-1
shows you the Workplace Designer import tool.
Figure 3-1 Tool for importing a Journal Domino database to the Workplace Designer
The goal of importing a Domino database is to let you quick-start your new Workplace
application, but you are not migrating one-to-one. Experience proves that when you want to
move from Notes to another environment, leveraging the new capabilities of the target
platform for a one-to-one move is more work. We decided to create our status report
30
IBM Workplace 2.5 Development with Workplace Designer
application from scratch. This allows a deeper understanding of all the basic features of a
Workplace Collaboration Services component right from the beginning.
3.1.1 Step-by-step: Creating a component from scratch
The following steps guide you through the creation of a new Workplace component.
1. If Workplace Designer is not running, select Start → All Programs → IBM Workplace →
Workplace Designer.
2. To create a new component, select File → New → Component.
a. Enter the name of your component. This name becomes the name of the component
listed in your Workplace Designer Component Navigator.
b. Enter the label of the component. After you deploy the component, this label becomes
the name of the portlet. We need to know the name of the deployed component
(portlet) if we add it to a page or a template. For more information about deploying
components refer to 3.7, “Deploying and testing” on page 68.
Figure 3-2 Create a new component
Important: If you leave the Label field blank, then the name of the component is the
portlet name.
3. Select Start with blank component.
4. Click OK.
Workplace Designer creates a container (or component), in which you can add the following
elements to your application:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Forms
UI controls
Schemas
Script libraries
Component scripts
Images
Chapter 3. Developing the sample application: Basic development topics
31
3.2 Creating a schema
This section discusses how to create the basic XML Schema Definition (XSD) schemas for
our status report application. Before we begin to create the forms and views that are used by
our component, we must define the underlying data structure. In a Workplace application, this
is done by creating schemas for objects that store data to the Workplace application.
Schemas
Any documents created from the deployed components are stored in a relational database as
XML documents. These documents are defined by XSD schemas that are assigned to the
elements used in Workplace Designer.
You can assign schemas to the following elements in Workplace Designer:
򐂰 Form (Designer Element)
򐂰 Panel (UI Control)
Documents that are generated from a form or panel are defined by the associated schema.
After associating a form or panel with a schema, the controls can be bound to elements of the
schema. Elements contain data that users enter through particular UI controls in forms. You
can use Workplace Designer to access elements of an XML document in different ways. One
possibility is to use the document database API (DocAPI), which we discuss in later chapters.
Alternatively, you can use the XML Path language (XPath).
XPath
Using XPath, you can access the elements of the XML data. XPath is completely integrated
with Workplace Designer. An XPath expression is a path to the location of element and
attribute nodes in an XML hierarchy. You can use XPath expressions to select nodes in an
XML document. They are similar to paths used by Microsoft Windows® or Unix to specify a
file location. You can execute an XPath in the JavaScript code just to query a document.
Tip: For more information about using XPath, refer to the World Wide Web Consortium
Web site:
http://www.w3.org/TR/xpath
Schema editor
Workplace Designer has its own schema editor to modify the schema. You can create
schemas in Workplace Designer using the Visual Editor, which provides a simple interface for
creating a structure of elements. Most of this section describes how to use that Visual Editor.
Alternatively, you can edit the raw XML with a text editor.
Adding a schema to a Workplace component
There are three ways to add a new schema to a component using the Workplace Designer:
򐂰 Create a new form and let Workplace Designer automatically create a schema for this
form. If necessary, you can use the schema editor to modify the schema later.
򐂰 Create a new schema using the schema editor.
򐂰 Import a schema using the Imported Schemas tab of the schema editor.
Using the schema editor, you can edit, create, or delete elements of the schemas or even
define your own data types. Although it is possible to modify the schema after associating it
with a form, we recommend defining the data structure of your application before you start to
add forms to the component.
32
IBM Workplace 2.5 Development with Workplace Designer
Our status report application uses the StatusReportEdit form. This form consists of several
fields that need to be stored to a database. Therefore, we create a schema, named
statusReport, that contains all necessary elements.
3.2.1 Step-by-step: Creating the status report schema
This section provides instructions for creating a basic schema for our status report
application. We are going to show:
򐂰 How to create a new schema
򐂰 How to add new elements to the schema
򐂰 How to modify properties of the elements
Creating a new schema
To create a new schema, follow these steps (after making sure that you have already created
a component):
1. Expand the StatusReport component in the Component Navigator by clicking the icon next
to the component name. Then double-click Schemas to open the schema editor in the
canvas.
Figure 3-3 Create a new schema
2. Click New Schema and enter the name statusReport and a description for this schema.
3. Click OK.
Based on your input values, Workplace Designer creates a schema with the corresponding
XML declaration. Furthermore, a root element is created that takes over the name of the
schema that was entered in step 2. In the next section, we add child elements to this root
entry.
Note: If you create a form and add controls to it that accept data, but do not associate the
form with an existing schema, Workplace Designer creates a schema for it with the name
Schema_formname.
Adding elements to the schema
Elements can be root elements, parent elements, child elements, or sibling elements. A root
element is at the top of the hierarchy. There are no elements above a root element, only
parent and child elements below. A root element is created as part of every new schema and
has the same name as the schema.
We need to create an element for each field that we want to store with our status report
document. Each element gets assigned to a data type, which actually are elements that other
elements reference to define the type of data that they can contain. For example, an element
with an integer data type can only contain integers. You can use standard data types such as
string, integer, or boolean, and you can create your own data types in the Data Types pane of
the Visual Editor.
Chapter 3. Developing the sample application: Basic development topics
33
Table 3-1 shows the elements that we need to create for our basic statusReport schema.
Table 3-1 Status Report elements
Element name
Data Type
Description
activity
string
Name of the activity
name
string
The distinguished name of the
author of the status report
commonUserName
string
The common name of the
author of the status report
userEmail
string
The e-mail address of the
author of the status report
date
date
Created date of the status
report
manager
string
The distinguished name of the
author’s manager
managerEmail
string
The e-mail address of the
author’s manager
summary
string
Description of the status report
As you enhance the application in further chapters, you add more elements to this schema
and create more schemas.
Follow these steps to add elements to the statusReport schema:
1. Open the Visual Editor for your schema.
2. Click the statusReport element entry of the schema and select Element → Insert
Element → As Child.
3. Enter the name of the element and assign the corresponding data type.
Figure 3-4 Adding a new element to a schema
To obtain a complete list of the supported data types, click the dotted button next to the data
type field. This is optional.
34
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-5 shows a clipping of the type dialog.
Figure 3-5 Adding data types to an element
4. Press Enter to add the element to the schema.
5. Repeat steps 2 and 3 for each element that you want to add to your schema. Refer to
Table 3-1 on page 34 for a complete list of the elements and data types we used in this
component.
6. You have the option of creating your own data types for this schema and assigning them to
elements. This is useful if you want to add a middle initial field to the application and
restrict it to accepting only one character. (For more information about this topic, refer to
the Workplace Designer Help.) After creating new data types, you can select them from
the data type menu shown in Figure 3-4 on page 34 or from the lower section of the dialog
shown in Figure 3-5.
7. Save your component. Either select File → Save or click the save icon in the menu bar. An
asterisk precedes the schema name at the top of the Visual Editor, if changes have not yet
been saved to the component. This is the case in Figure 3-4 on page 34.
Tip: You can use File → Save As to save the current schema to another location. This can
be useful if you only want to make a snapshot of the current schema.
Figure 3-6 on page 36 shows you how your statusReport schema looks in the Visual Editor
after you create the elements.
Chapter 3. Developing the sample application: Basic development topics
35
.
Figure 3-6 Schema for the basic status report component
Information: You can use the Insert and Delete keys to create or remove elements in your
schema. Be sure to mark the statusReport root element, if you want the new element to
become a child element of the statusReport schema and a sibling element of the other
elements.
Figure 3-7 shows how your schema appears in the text editor. If you are familiar with XML
schemas, you can also use this editor to modify the schema.
Figure 3-7 statusReport schema in the Text Editor
Adding properties to elements
Data entered in forms is stored in XML documents. To store the data, you must bind the
controls in the form to elements (also referred to as fields) in a schema. An element defines
data for controls that are bound to it. The application allows users to enter data into a control
that does not conform to the definition in the element.
Using the schema editor, we are able to add more data type information to an element such
as validation or constraints. We want to use this feature in our status report application to
ensure that an activity name is entered before the document is saved.
To add a validation property to the activity element, follow these steps:
1. Open the statusReport schema in the canvas.
2. Click the activity element. A property pane opens below the Visual Editor.
36
IBM Workplace 2.5 Development with Workplace Designer
3. Click the Basics tab of the Properties pane and select A value must be specified. This
means that whatever control is eventually bound to this element must have a value, which
in turn means that application users must provide a value in that control before they can
save the application.
Figure 3-8 Adding validation to the elements
4. Save and close the schema.
If this element is bound to a field, it is also automatically added to a form as a required field.
We discuss this procedure in detail in the following sections.
Tip: The possibilities for extending XML in schemas are vast and extensively documented
on the Web. For detailed documentation on XML and XML schemas, refer to the World
Wide Web Consortium Web site:
http://www.w3c.org
3.3 Creating a form
Forms are the basic elements in which Workplace Designer operates. You use forms to
expose and save the elements that are created in the schema.
You start by going through the steps that are used to create the basic form with fields. In the
process, you create nested tables to help with the layout of your form.
Tip: If you are planning to use tables to dictate the layout of an application, you should
disable the automatic labeling that is on by default. To do this, select File →
Preferences → Forms and clear Enable automatic labeling of controls.
You use JavaScript to help create fields that populate themselves as computed fields and
triggered events.
Chapter 3. Developing the sample application: Basic development topics
37
Tip: Once you are familiar with Workplace Designer and the JavaScript classes, you might
want to enable the advanced JavaScript classes option to see more information in the
content assistant. To do this, select File → Preferences → JavaScript and select Show
advanced JavaScript classes and methods.
Tip: Note that you are also able to enforce code completion using CTRL-Space in the
Script Editor.
Tip: To find your problems in JavaScript code, it is advisable to enable the error tab so that
you can obtain a listing of the errors and be able to jump to them. To do this, select File →
Preferences → Property Tabs and select Errors.
3.3.1 Step-by-step: Creating a form
You create the form of your application by first generating the form and mapping schema
elements, then expanding upon your form with computed fields and events that fire as the
form is opened and saved.
Creating a form with basic fields
To create a form with basic fields, follow these steps:
1. Open the component you created.
2. Next, select File → New → Form. Alternatively, you can double-click Forms under the
Component Navigator, then select New Form from the canvas.
3. In the New Form window, name the form StatusReportEdit and choose the statusReport
schema as shown in Figure 3-9.
Figure 3-9 New Form Pane
4. You are now ready to start adding fields that allow viewing and editing of your schema
elements. Start by creating a table for the fields. Select Table from the UI Controls window,
and click at the top of the blank page to place it.
38
IBM Workplace 2.5 Development with Workplace Designer
5. Because a 2 x 3 table is the default, right-click in the table cell and select Delete
Columns. Choose 2, and click OK as shown in Figure 3-10.
Figure 3-10 Deleting columns of a table
6. To resize the table, click inside a cell, then using the Properties panel, select Table from
the down triangle on the Properties panel.
7. Go to the Basics tab. Change Width to 600 pixels.
8. Set the height of each row by clicking the dotted line of the table on each row to obtain the
Basics tab. Change the bottom cell height to Auto, and the top cell to a height of 17 pixels.
9. You can also add a border to the table. Select Format → Border, and fill the top cell under
the Background section. We used RGB(82,132,189) for the border and
RGB(214,239,247) for the background respectively.
10.We used the top cell of the table as a title section and the bottom cell for data. Create two
more tables in the bottom cell, with the top table being a 2 x4 table and the bottom a 1 x 3
as shown in Figure 3-11.
Figure 3-11 Blank nested table
11.To begin populating the table, create an edit box. Type Activity: in the top-left cell, click in
the cell to the right of Activity, and select Edit Box from the UI controls. Put it in the cell
with a click.
Chapter 3. Developing the sample application: Basic development topics
39
12.Now you must bind this new field to the appropriate schema element from the Data tab in
the Properties panel. Select Activity for the Data binding. The result is shown in
Figure 3-12.
Figure 3-12 Adding Edit Box control
13.Fill the rest of the table in the same way using the data bindings listed in Table 3-2, and
resize the cells to your liking. We selected Multiline Edit Box for the Summary field to
allow for more text.
Table 3-2 Application data bindings
Label of Edit Box
Data Binding for Edit and Multiline Edit Boxes
Name
commonUsername
Manager
manager
Date
date
Summary
summary
14.Create a Computed Field below the Name field that you created until your application
resembles Figure 3-13.
Computed Field
Figure 3-13 A simple form with edit boxes
40
IBM Workplace 2.5 Development with Workplace Designer
Expanding the form with computed values
To expand the form, follow these steps:
1. Click the edit box for the Date field.
2. In the Properties pane, select Data, then click to the right of the Default Value edit box and
select Computed.
Figure 3-14 Setting Default value to Computed
3. This launches the JavaScript Editor (Figure 3-15), which is where you can put the code
shown in Example 3-1.
Example 3-1 JavaScript Code for Date
retToday = new Date();
return retToday;
Tip: You can also write the code shown in Example 3-1 using @Functions as follows:
return @Today()
Figure 3-15 JavaScript editor
4. Click the computed field that you created under the Name field.
Chapter 3. Developing the sample application: Basic development topics
41
5. Click Value under the Properties panel, and paste the code in Example 3-2 into the
JavaScript Editor. This pulls the e-mail address out of the document for display using the
XPath language. For more information about the XPath language, see the Workplace
Designer Help. This does not populate the back-end userEmail object; it simply shows the
address.
Example 3-2 Pull the e-mail from the document
"("+document.getStringValue("/statusReport/userEmail")+")";
Tip: If you wish to paste code into the embedded JavaScript editor, you must first highlight
the code, right-click it, and select Paste. When using the JavaScript Editor pane, however,
you can paste the code directly into the pane using shortcut keys.
Adding events to the form
You can add events to the form as follows:
1. Click the down arrow to the far right of the Properties panel and select Form as shown in
Figure 3-16.
Figure 3-16 Properties menu
2. Click the Events tab, then click onPostNewDocument.
3. Click Script Editor... and put the code shown in Example 3-3 in the editor. This sets your
commonUsername schema element to the current user based on the session, and
automatically populates your computed field with the e-mail address of the user.
Example 3-3 JavaScript code for onPostNewDocument
var entry:DirectoryEntry;
var currentDn = session.getDistinguishedUserName();
document.setStringValue("/statusReport/name",currentDn);
document.setStringValue("/statusReport/commonUsername",session.getCommonUserName());
entry = context.getDirectory().searchUser(currentDn, null);
var user = context.getDirectory().getDirectoryUser(entry.getDn());
document.setStringValue("/statusReport/userEmail", user.getMail());
3.4 Creating buttons
Although you have created a basic form, at this point, other than setting fields, you cannot do
anything with it yet. Therefore, the next step is to add various buttons to expand the
functionality of the form. The topics are as follows:
򐂰
򐂰
򐂰
򐂰
42
Creating basic buttons and button types
Hiding buttons
Creating specialized buttons
Using a script library
IBM Workplace 2.5 Development with Workplace Designer
With Workplace Designer, not only can you add basic buttons, but you can also specify the
button types. Such specifications assign default behaviors to make the logic behind the
buttons easier to implement. Example 3-3 reviews the four types of buttons.
Table 3-3 Button types
Button type
Functionality
Simple
No extra functionality provided
Submit
򐂰
Saves the document
򐂰
Refreshes the form to the form properties
under Next page
Reset
Clears all the fields on the page that are not
computed
Cancel
Ensures that required fields are not needed
Note: Once you add any code to a Submit button, it becomes a simple button and you
must handle your own document saving and redirection.
3.4.1 Step-by-step: Adding buttons
For your application, you are going to add four buttons to your form: Save, Cancel, Edit, and
Lookup. While the first three are fairly self-explanatory, the fourth is a little more specialized.
This button allows users to enter a manager name and automatically retrieves the information
from the user store. Also, you want to make sure that certain buttons only appear when they
are needed, such as the Edit button.
Creating a basic button and button types
To create a basic button and button types, you use the following process:
1. On the StatusReportEdit form, add two carriage returns above your main tables.
2. Click the Button object in the UI Controls pane and then click at the top of the form as
shown in Figure 3-17.
Figure 3-17 Adding a button
3. Next, click the button so that the Properties panel changes focus. Click the Basics tab.
Chapter 3. Developing the sample application: Basic development topics
43
4. Change the Label field to Save & Submit. Click the check mark to the right to confirm the
change.
5. Because this is going to be a Save button, you must change the Button type to Submit.
6. You also have the option of changing the sizes of buttons using the Height and Width
properties. In our application, we chose Auto for the height and width of all buttons.
Figure 3-18 shows the results.
Figure 3-18 Button Properties.
7. To make sure that our look was consistent with the Workplace applications already in the
server, we set the style in the Format tab of the Properties panel by selecting Apply an
existing style. In our application, we used the Portlet Form-Related Text category with the
portlet-form-button style for all our buttons. You can do the same with your buttons.
8. Repeat steps 2 through 7 to create two more buttons next to the Save button. Label them
Cancel and Edit.
9. Set the Button type for the Cancel button to Cancel and keep the Edit button as a Simple
button.
10.For the Cancel button, go to Events in the Properties pane. Click onClick.
11.Change the event to Simple Actions. Click Add.
12.Select Open a form. Set the AllStatusReports form as New Document.
13.For the Edit button, go to Events in the Properties pane. Click the onClick event to the left.
14.Change the event to Simple Actions and click Add.
44
IBM Workplace 2.5 Development with Workplace Designer
15.Select Change document mode. For the Document mode, select Edit mode as shown in
Figure 3-19.
Figure 3-19 Adding a simple action
16.Your form should resemble that in Figure 3-20.
Figure 3-20 Form with all buttons added
Hiding buttons
Because you do not want to show all the buttons all the time, you need to be able to hide them
based on the current state of the document. Begin by clicking the Save button and going to
the Basics tab on the Properties panel. Then, follow these steps:
1. To the right of the Visible property menu, select the Computed option as shown in
Figure 3-21 on page 46.
Chapter 3. Developing the sample application: Basic development topics
45
Figure 3-21 Setting visible property
2. In the JavaScript Editor, enter the code from Example 3-4.
Example 3-4 JavaScript to check if a document is editable
document.isEditable();
3. Repeat steps 1 and 2 for the Edit button, but use the code in Example 3-5, which ensures
that the Edit button is only seen when the document is not already in that mode.
Example 3-5 JavaScript to check if a document is not editable
!document.isEditable();
Creating a specialized button
The last buttons that you create in your form auto-populate the e-mail address of a manager
from the user store and then create the option to change the manager if the user mistyped the
name. You also can create new fields for the e-mail address and a possible error state. In
addition, the new buttons and fields need logic to ensure that they are only available when
necessary.
For example, if a manager name has not been entered, only the blank manager field and
Lookup button must be available. After a user clicks Lookup, the manager name as it was
found in the user store must be populated in the field, the Lookup button must no longer be
visible, and the Change button must be visible in case the user made a mistake.
For this logic, you use two custom functions. The first, getDirectoryUser, obtains the user
based on an expected distinguished name, which you can wrap with the second function,
isStringUser, which returns a boolean value if the user is found in the directory. With these
two functions, you can write the visible check statement that confirms that the document is in
edit mode and verifies if a user has already been looked up.
To create the lookup feature, follow these steps:
1. Create two Computed Field boxes and two buttons in the same cell as the current
manager.
2. Label the buttons Lookup and Change as shown in Figure 3-22 on page 47.
46
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-22 Manager cell updates
3. Edit the onClick event for the Lookup button so that it has the code shown in Example 3-6.
Example 3-6 JavaScript for Lookup button
var managerName = document.getStringValue("/statusReport/manager");
var entry:DirectoryEntry;
try{
entry = context.getDirectory().searchUser(managerName, null);
var user = context.getDirectory().getDirectoryUser(entry.getDn());
document.setStringValue("/statusReport/manager", user.getDistinguishedName());
document.setStringValue("/statusReport/managerEmail", user.getMail());
pageData.hasSearchFailed = false;
}catch (e){
print(e);
pageData.hasSearchFailed = true;
}
Note: For the code in Example 3-6, and all remaining code in this paper, we used the Run
on server option for our JavaScript so that code was not sent to the client, potentially
exposing business logic. However, if you have occasions where you would like things to
recompute quickly for the client and updating the server state is not necessary, then the
Run on client option would be best.
Note: Client-side scripts can access only a certain number of JavaScript classes (the ones
that the browser can run itself). If you want the DocAPI, sessionData, pageData, and
others like them, you must use server-side scripts only.
Tip: Remember that server-side scripting cannot directly interact with the browser user.
For example, the window.alert function is not available. If you want to print, use the
following functions to write to the SystemOut.log on the Workplace Collaboration Services
portal server (for example, C:\WebSphere\PortalServer\log\SystemOut.log):
򐂰 print(string) writes a string.
򐂰 _dump(object) writes a string representation of the object.
Chapter 3. Developing the sample application: Basic development topics
47
4. Set the visible property of the Lookup button with the code from Example 3-7.
Example 3-7 JavaScript for Lookup visible property
function isStringUser(context:XSPContext, username:string) {
try {
return (getDirectoryUser(context, username) != null);
} catch (e) { // Directory search failed; string is not a user.
return false;
}
}
function getDirectoryUser(context:XSPContext, username:string) {
var entry = context.getDirectory().getEntry(username);
return context.getDirectory().getDirectoryUser(entry.getDn());
}
return document.isEditable() && !isStringUser(context,
document.getStringValue("/statusReport/manager"));
5. Add the code in Example 3-8 to the onClick event for the Change button.
Example 3-8 JavaScript for Change button
function getDirectoryUser(context:XSPContext, username:string) {
var entry = context.getDirectory().getEntry(username);
return context.getDirectory().getDirectoryUser(entry.getDn());
}
var username = document.getStringValue("/statusReport/manager");
var dirUser = getDirectoryUser(context, username).getCommonName();
document.setStringValue("/statusReport/manager", dirUser);
6. Use the code in Example 3-9 in the Visible property of the Change Button.
Example 3-9 JavaScript for Change visible property
function isStringUser(context:XSPContext, username:string) {
try {
return (getDirectoryUser(context, username) != null);
} catch (e) { // Directory search failed; string is not a user.
return false;
}
}
function getDirectoryUser(context:XSPContext, username:string) {
var entry = context.getDirectory().getEntry(username);
return context.getDirectory().getDirectoryUser(entry.getDn());
}
return document.isEditable() && isStringUser(context,
document.getStringValue("/statusReport/manager"));
Note: This is the same code as that in Example 3-7, except that we did not invert the
result of isStringUser.
7. Change the first computed box to have a Value (in the Properties panel) that is based on
the JavaScript in Example 3-10, so that the e-mail address for the manager is
automatically populated.
48
IBM Workplace 2.5 Development with Workplace Designer
Example 3-10 JavaScript for the value of e-mail computed field
function isStringUser(context:XSPContext, username:string) {
try {
return (getDirectoryUser(context, username) != null);
} catch (e) { // Directory search failed; string is not a user.
return false;
}
}
var display:string;
var manager = document.getStringValue("/statusReport/manager");
var managerEmail = document.getStringValue("/statusReport/managerEmail");
if (isStringUser(context, manager)) {
var user = context.getDirectory().getDirectoryUser(manager);
display = user.getCommonName() + " (" + managerEmail + ")";
}
return display;
8. Change the Visible property so that it matches the JavaScript in Example 3-11. This
ensures that it only appears after an attempt to look up the manager.
Example 3-11 JavaScript for the Visible property of the e-mail computed field
document.getStringValue("/statusReport/manager")!="";
9. For the last computed box, put the contents of Example 3-12 as the value. This provides
an error message functionality for the Lookup button.
Example 3-12 JavaScript for value of error message computed field
"Unable to locate user '" + document.getStringValue("/statusReport/manager") + "' in the
directory. Make sure you have typed the name correctly and pressed the Lookup button."
10.Change the color and style of the text to red and bold on the Format tab of the Properties
panel.
11.Change the Visible property of this computed box to the code shown in Example 3-13, so
that it is only shown when the pageData element has been set by the code in Example 3-6
on page 47.
Example 3-13 JavaScript for Visible property of error message computed field
document.isEditable() && pageData.hasSearchFailed;
12.Change the Visible property of the Manager field to match the code in Example 3-14 on
page 50 so that the input box can hide after the user has performed a lookup.
Chapter 3. Developing the sample application: Basic development topics
49
Example 3-14 Visible property of manager edit box
function isStringUser(context:XSPContext, username:string) {
try {
return (getDirectoryUser(context, username) != null);
} catch (e) { // Directory search failed; string is not a user.
return false;
}
}
!isStringUser(context, document.getStringValue("/statusReport/manager"));
Using a script library
As you might have noticed in the previous section, the need to use the same code or
functions numerous times can be quite common. For example, in Example 3-7 on page 48,
Example 3-9 on page 48, Example 3-10 on page 49, and Example 3-14, we used
isStringUser in each one. Fortunately, script libraries eliminates the need to do this.
In this section, you learn how to create a new script library and move common functions into
that library. Then, any future shared code can be put in a library so that you only have to write
or change it in one place.
Creating a script library
1. Select File → New → Script Library, or, alternatively, expand Scripts under Component
Navigator, double-click Script Libraries and click New Script Library in the Component
canvas.
2. In the New Script Library page, give the library called UtilityScripts a description.
Tip: You can also create script libraries by clicking Save As... in the JavaScript editor.
You are asked to give a name, which becomes the name of the library. Any code you
typed in the editor also appears in the library.
3. Cut isStringUser and getDirectoryUser from previous examples and paste them into the
UtilityScripts library. Your JavaScript editor should resemble that in Figure 3-23.
Figure 3-23 UtitlityScripts
50
IBM Workplace 2.5 Development with Workplace Designer
4. In any of the places where you cut the function, add this statement:
import UtilityScripts
Now your buttons and fields can find the moved functions (Figure 3-24).
Figure 3-24 Adding import statements
3.5 Creating a view
A view is a basic database object that displays a list of documents from the database. A visual
representation of a view is usually a table, where each column displays a different type of
information and each row belongs to one specific document.
Views are designed to be able to effectively select a subset of documents that have
something in common. For example, we often want to display documents that were created
using a certain schema.
Another typical characteristic of views is that they can be sorted by values in one or more
columns. For example, in a view in a corporate phone directory, we can sort the employees by
their last names.
3.5.1 Views versus view controls
In Workplace Designer, you cannot create view objects directly in the database. Instead, you
create view controls in forms. Whenever you put a view control in a form, a physical view
object is created in the database behind the scenes when you deploy the component.
Chapter 3. Developing the sample application: Basic development topics
51
Workplace Designer does not limit the number of view controls that you can have in a form.
This means that you can combine various views in one form and each of them can have
different selection criteria or sort conditions.
In the next section, you learn how to create a view for the sample application.
3.5.2 Step-by-step: Creating a view
In this section, we are going to show you:
򐂰
򐂰
򐂰
򐂰
How to create a view that displays documents with one specific schema.
How to add simple columns to the view.
How to add computed columns to the view.
How to add buttons to create and delete documents.
Creating a new form with a view control
You can create a new form with a view control by following this procedure:
1. In your work space, choose the StatusReport component from the Component Navigator.
Right-click Forms and choose New → Form as shown in Figure 3-25.
Figure 3-25 Create a new form (1)
2. Change its name to AllStatusReports. Select Do not use a schema as shown in
Figure 3-26 on page 53. Click OK.
52
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-26 Create a new form (2)
3. The next step is to create a table that contains the view and a label belonging to it. This is
very useful for managing, for example, the visibility of more than one visual component at
the same time (we show you how to do that later). To create the table:
a. From the UI Controls pane, click and drag a Table control to the form.
b. Because you need only one row and one column, you remove the others. Select the
last two columns in the table and from the main menu, select Element → Table →
Remove column(s)... and in the Number of columns field, enter 2.
c. Select the last row in the table. From the main menu, select Element → Table →
Remove row(s)... and leave the number of rows set to 1.
4. To add a label control to the form, select the Label control (located under Core Controls)
from the UI Controls pane. Click anywhere in the table in the form to put a new label
control there and follow these steps:
a. In the Properties pane, select Basic and type All Status Reports: into the Label
property. Click the check button, or press Enter (see Figure 3-27 on page 54).
b. Change to the Format tab. In the Font element, click a spot next to the Style property
and select Bold.
Chapter 3. Developing the sample application: Basic development topics
53
Figure 3-27 A label and its properties
5. You are now ready to create your first view. From the UI Controls pane, pick up the View
control (located in the Container Controls group) and click under the All Status reports
label to put it in the form. Then, follow these steps:
a. Select the view control by clicking somewhere on its border, if it lost focus.
b. In the Properties pane, select the Basic tab and enter a name for this new view:
allStatusReportsView.
c. You might find it useful to set the width and height properties to Auto (see Figure 3-28
on page 55).
54
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-28 A view control and its basic properties
6. Click the Data tab and in the Schema property, select the only StatusReport option as
shown in Figure 3-29.
Figure 3-29 Setting the schema property of a view control
Note: The Schema property provides the most basic selection criteria for a view. The view
only contains documents that were created using this schema. You must select at least one
schema; otherwise, your view will contain no documents.
Populating the view with columns
There are two types of columns that you are going to use in this example:
򐂰 Data field columns (simple)
򐂰 Computed columns (advanced)
Chapter 3. Developing the sample application: Basic development topics
55
Columns with data field bindings provide the easiest way to design views quickly. Each time
you create a new simple column, Workplace Designer lets you select one of the available
data fields according to the schemas enabled for the view (shown in Figure 3-30). You are
allowed to choose exactly one data field for each column this way.
Figure 3-30 Data field binding example
Columns that contain computed formulas offer a more powerful way to specify what kind of
information you want to display. Computed columns consist of a JavaScript formula (see
Figure 3-31) that is evaluated for each document displayed in the view. The result of this
formula is then printed to the appropriate column of the view.
Figure 3-31 Formula binding example
Planning the view
The outline of the view that you are going to create is shown on Figure 3-32.
Figure 3-32 Outline of the sample view
Table 3-4 lists a description of all columns.
Table 3-4 Columns in the sample view
56
Name
Type
Content
Hidden Date
Data field
Hidden column used for sorting
Check Box
Computed
Check boxes used for selecting documents
Date
Computed
Formatted date value
Activity
Data field
Simple text value
Person name
Data field
Simple text value
View
Computed
“View” links to open documents (in read mode)
Edit
Computed
“Edit” links to open documents (in edit mode)
IBM Workplace 2.5 Development with Workplace Designer
Designing the view
The first column was created when you added the view control on the form and is ready to
use. To design the view, follow these steps:
1. Click the header, the columnHeader_1 label.
a. In the Properties pane, select Basic and change the Label field to (Hidden Date) and
click the small mark or press Enter (see Figure 3-33).
Figure 3-33 Modifying view header’s properties
b. Click anywhere in the body of the column. In the Properties pane, select Data.
Choose date from the Data field menu (see Figure 3-34).
Figure 3-34 Adding data field binding to the view column
c. This is a special sort column and you do not want it to be displayed for users. That is
why we returned to the Basic tab and set its Visible property to False. After this
operation, the column becomes grey, as shown in Figure 3-35 on page 58.
Tip: If you cannot see your item in the Data field menu, verify that the Schema property of
the view control is set to the correct schema.
Chapter 3. Developing the sample application: Basic development topics
57
Figure 3-35 Making a column hidden
2. To add a new column, right-click anywhere in your view control and select Add column:
a. Click the header of the new column. In the Properties pane, select Basic and leave the
the name of the column header blank (you do this because you do not want to use any
header for the check boxes).
b. Click the body of the column. In the Properties pane, select Basic and Check box.
c. From the same tab, set the width of the column to 20 pixels (see Figure 3-36 on
page 59).
58
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-36 Adding a check box column
d. Go to the Data tab. Click Formula and type two quotation marks ("" ), which means an
empty string, in the field to the right of the Formula label (you do this because you do
not want to use any text in this field).
e. Go to the Format tab and clear Apply existing style as shown in Figure 3-37;
otherwise, a solid border is visible in the browser.
Figure 3-37 Modifying the format of the check box column
3. Add a new view column by right-clicking anywhere in the view control and selecting Add
column from the menu:
a. Click columnHeader_3. Go to the Properties pane, click the Basic tab and change the
Name property to Date.
b. Go to the Data tab, select Formula, and enter the code shown in Example 3-15 on
page 60 in the field for the Formula label, as shown in Figure 3-38 on page 60. (You
can also use the script editor introduced earlier in this chapter, if you are more familiar
with the editor.)
Chapter 3. Developing the sample application: Basic development topics
59
Example 3-15 Formatted date field
document.getDateField(“statusReport/date”).toDateString()
Note: The code in Example 3-15:
1. Accesses the object of the current document
2. Gets the date field from the current document, by its full XPath (statusReport/date)
3. Converts it to a string, using only its date part (ignoring the time information)
Figure 3-38 Adding a computed field
4. Add another view column by right-clicking the view control, then selecting Add column:
a. Set the header label to Activity.
b. Click the body of the column. Go to the Data tab and select activity in the Data field
combo box.
5. Add a view column again by right-clicking the view control, then selecting Add column:
a. Set the header label to Person name.
b. Click the body of the column. Go to the Data tab and select commonUsername from
the Data field menu. Your view should look like the one shown in Figure 3-39.
Figure 3-39 View design checkpoint
6. There are two more columns remaining. First you add a column that displays hyperlinks so
that a user can open the document by clicking them. To do this, add a new column to the
view by right-clicking the view control and selecting Add column:
a. Set the header label to View.
60
IBM Workplace 2.5 Development with Workplace Designer
b. Click the body of the column. Go to the Basic tab, select Show values in this column
as links, and click Read-only, which is to the right of the Document open mode label.
c. Go to the Data tab, select the Formula option from the Column binding group, and type
"View" in the field for the formula. This is a JavaScript formula, so you must include
both quotes.
7. Now you use the same method to add an Edit column that allows users to open their
documents directly in edit mode. Right-click your view control, and select Add column:
a. Set the header label to Edit.
b. Click the body. Go to the Basic tab, select Show values in this column as links, and
click Edit, which is to the right of the Document open mode label.
c. Go to the Data tab, select the Formula option from the Column binding group, and type
"Edit" into the formula edit-box, including the quotes.
You have completed your column designs. Now you can set up the sorting feature as follows:
1. Highlight the view in the form by clicking somewhere in the border.
2. In the Properties pane, select Sort/Filter. Make sure that Sort first by this column is set
to column_1 (as illustrated in Figure 3-40).
Figure 3-40 Sorting a view
Adding buttons
To add buttons:
1. Click the UI Controls pane and select Button. Put it in the form below the All status reports
label (Figure 3-41).
Figure 3-41 A Create button
Chapter 3. Developing the sample application: Basic development topics
61
a. In the Properties pane, click the Basic tab, and change the Name property to Create.
b. While you are still in the Basic tab, you can set the width and the height of the button to
Auto (Figure 3-42). This is optional.
Figure 3-42 Create button basic properties
c. Another option is to click the Format tab and select Apply an existing style:
i. Set Select style category to Portlet Form-Related Text.
ii. Set Select style to portlet-form-button.
Note: The portlet-form-button is the recommended style for buttons in Web applications.
However, you can use another style, your own style, or you can leave the style of the button
unspecified. If you use this style, it is advisable to set the width and height properties of the
button to Auto (as described previously).
d. Click the Events tab, select onClick, and change its type from JavaScript to Simple
action.
e. Click Add to add a simple action. In the Add simple action dialog box (see Figure 3-43
for illustration), take the following actions:
i. From the Action menu, select Open a form.
ii. Select StatusReportEdit as the name of the form.
iii. Do not change New document and Edit.
Figure 3-43 Simple action: Create document
62
IBM Workplace 2.5 Development with Workplace Designer
2. Now you are going to add a button to delete documents. Return to the UI Controls pane,
click the Button control, and put a new button next to the existing button. (The next four
sub-steps are very similar to the ones you performed for the previous button).
a. In the Properties pane, click the Basic tab, and change the Name property to Delete. If
you wish, set the width and the height of the button to Auto. Remember, the Auto
setting is optional but recommended for this sample application.
b. This step is optional but recommended for this sample application. Click the Format
tab. Select the Portlet Form-Related Text category and the portlet-form-button style.
c. Click the Events tab, select the onClick event, and change its type from JavaScript to
Simple action.
d. Click Add to add a simple action and perform the following steps in the Add simple
action dialog (see Figure 3-44 for illustration):
i. From the Action menu, select Delete selected documents.
ii. Leave view_1 unchanged.
iii. Type a confirmation text such as Are you sure?
Figure 3-44 Simple action: Delete selected documents
Modifying the forms to use views
When we created our first form we did not have a view that we could redirect our form back to.
In our StatusReportEdit, we made use of a submit button type, which uses the Next Page
property of a form. This property is what directs the component to the next logical page. You
can modify forms to use views as follows:
1. Open the StatusReportEdit form.
2. Go to the Basics tab on the Properties pane for the form as shown in Figure 3-16 on
page 42.
3. Set the Next Page (successful update) property to other page and select the
AllStatusReports form.
4. Keep the Next Page (if update fails) property to the current page.
Note: We are not creating an error page in this application, but you can decide to
change the setting to always send users to an error page that you create.
Chapter 3. Developing the sample application: Basic development topics
63
3.5.3 Other information about view properties
Figure 3-45 shows the properties available in the Basics tab in the Properties pane. In this
section, we examine some of these properties.
Figure 3-45 View control Basic properties
Name of the view
The name of the view control is an identifier that can be used to access view objects
programmatically from JavaScript code. By default, Workplace Designer generates a default
name for every view that you create. However, for easier debugging, we recommend that you
give a descriptive name for your views.
Note: Workplace Designer creates each view to have a unique name. This means that no
two view controls can share the same name, even if they are in different forms.
Visibility
Just like other UI controls, views also have a property called Visible, which lets you hide a
view in some cases, depending on a computed formula.
Note: Hidden views in a form are not built by the server at display time. This means that
they do not have a negative impact on the performance of the server.
View navigation
The Maximum rows per page property lets you limit the number of documents that a view
control displays at once.
To be able to access other documents that did not fit into the limited number of documents on
a page, set the View navigator property to Top, Bottom, or both.
If the View Navigator is enabled, it contains a limited number of pages that a user can
navigate. In this case, you might be interested in altering this limit by setting the Maximum
page count property.
64
IBM Workplace 2.5 Development with Workplace Designer
Data selection and filtering
Workplace Designer offers four ways to define which subset of documents from the database
should be displayed in the view. The filters are layered on top of one another with one
required filter, and three optional filters. They are:
1. Mandatory:
a. Specify the schema of displayed documents (Data → Schema).
2. Optional:
a. Write a static query string that defines selection criteria for particular columns (select
Data → Dynamic conditions).
b. Write a JavaScript expression, which is evaluated for each document and its return
value, to determine if a document is shown or not (Data → Static conditions).
c. Write a JavaScript that returns a query string that defines selection criteria for
particular columns (Filter → Dynamic conditions).
In this chapter, we explained the mandatory technique. Chapters 4 and 5 introduce the
optional ones.
3.6 Data validation
Workplace Designer validates data. In other words, it checks the data that a user enters into a
control against the data definition of the element that the control is bound to. For example, you
can create an edit box control and bind that control to a string element in a schema. If the
element is defined as having a maximum length of five characters, and the user enters six
characters into the control, Workplace recognizes the entry as invalid.
You can specify various validation settings in the Validation section of the Data tab for a
control. For example, you can specify whether the element requires the user to enter data and
whether that data must match a pattern. You can also create an error message for users
whose data is not valid.
3.6.1 Step-by-step: Adding validation to the status report application
In this section, we show you how to add validation to the fields of the status report application.
See Table 3-5 for a list of these fields.
Table 3-5 Setting validation for status report fields
Element name (field)
UI control name
Description
activity
edit_1
Required field based on
schema element validation
date
edit_4
Required field and date format
validation
manager
edit_3
Required field
If you added the UI controls in the same order as described in 3.3, “Creating a form” on
page 37 and you did not change their names, your UI controls have the names listed in
Table 3-5. You can inspect the name of your control in the Basics tab of your UI Controls
Properties pane.
Chapter 3. Developing the sample application: Basic development topics
65
To add validation to the Activity field on the form, follow these steps:
1. Open the StatusReportEdit form that you created in 3.3, “Creating a form” on page 37.
2. Click the edit box, which was bound to the Activity element.
3. In the Properties pane of the marked edit box, click the Data tab.
4. See the Validation section at the right of the Data pane. Notice that the check box called
Required Field is already set for this UI control. This is because you defined the Activity
element in the statusReport schema to require a value. For more information about this
subject refer to “Adding properties to elements” on page 36.
5. Enter a required field error message. Users see this message when they do not enter data
in this field and try to save it. Figure 3-46 shows the canvas with the marked Activity UI
control and the corresponding Validation section of the Properties pane.
Figure 3-46 Adding validation to UI controls
Next, we want to add validation to the Date field:
1. Click the edit box that is bound to the Date element.
2. Define this UI control as a required field by following the steps for the Activity field and
enter an appropriate required field error message.
3. From the menu for the Date/time Format field, select MM/dd/yyyy.
4. Click Format to user time zone.
5. Enter a validation error message. Figure 3-47 on page 67 shows the validation section for
the date field.
66
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-47 Setting validation for the date field
6. Repeat steps 1 and 2 to set validation for the Manager edit box. For the required field error
message, type:
Please type in the name of your manager and click on the 'Lookup' button.
7. This step is optional. You can assign Match pattern to UI controls. That is, if the value of
the field does not match the specified pattern, a validation message is displayed. Patterns
are defined by regular expressions, which apply to String field types only. The Match
pattern field is located in the Validation section of the Data tab for UI Controls.
You can type a pattern of characters that indicate the type and position of characters that
are allowed in the field. Click Test Pattern. In the Test Pattern dialog, enter a proposed
pattern that the value of the element must match. You can test the pattern by entering a
string and clicking Run Test. Workplace Designer tells you whether the string matched the
pattern.
Figure 3-48 shows a regular expression that allows a test string to contain only letters of
the alphabet in either case and white spaces. Furthermore, the string must have a
minimum length of four characters and a maximum length of 32 characters.
Figure 3-48 Test Pattern dialog showing a proposed pattern and a test string
Tip: For more information about using Regular Expressions, refer to:
򐂰 Regular Expression Library:
http://www.regexlib.com/
򐂰 RegEx Tutorial:
http://www.delorie.com/gnu/docs/regex/regex_toc.html
8. Save and close the StatusReportEdit form.
Chapter 3. Developing the sample application: Basic development topics
67
3.7 Deploying and testing
Now that you have spent time building your component, you can create a test deployment to
make sure that you did not make a mistake. In this section, you learn how to deploy the
component and roll it out into a personal portal page as a portlet.
Note: The deployment that is described in this section is simply used to test the application
and is not considered a full deployment of an application. For a discussion of full
deployment, see Chapter 6, “Templates” on page 145.
3.7.1 Step-by-step: Deployment
For the test deployment, follow these steps:
1. Select File → Component → Deploy, or, alternatively, click the icon with the green arrow
going to the server.
2. If you have not done a deployment previously, set up the Deployment profile as follows:
a. Click Add... on the Deploy Component window.
b. Name your deployment profile something descriptive such as WorkplaceDevelopment.
c. Enter the host name of the server in the Server name or address field.
d. Provide an installation directory in the server where Workplace Collaboration Services
is installed. You can use a mapped drive to the Workplace install folder or the full
Universal Naming Convention (UNC) path if it is shared. For example, in our server, the
D:\IBM\Workplace folder was shared as \\Server\Workplace.
Note: The directory that is shared is not the Workplace Server directory but the next
level up.
e. If you are using a default server, the Context root is lwp and the Port is 9081.
f. Enter a Workplace Collaboration Services administrator name and password
g. Choose the database server in use in the Workplace Collaboration Services server.
h. Provide the user ID and password for the database server.
i. In the JDBC Options field, provide the JDBC (Java Database Connectivity) driver if you
need a specific one or leave it blank.
j. Type the JDBC URL for your server, for example:
jdbc:db2j:net://wcs251.cam.itso.ibm.com:1527/lwpd;create=true
k. Change Pool options and JNDI key if necessary. The defaults were fine for our setup.
The completed profile looks like Figure 3-49 on page 69.
Tip: For more information about deployment profiles see Creating and editing
deployment profiles in Workplace Designer Help.
68
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-49 Sample deployment profile
3. As soon as you have a deployment profile in the Deploy Component window, you can
click OK to send the WAR file to the server and have it installed.
Tip: If you have any errors or problems when attempting to deploy, make sure that:
򐂰 No JavaScript errors exist in the Errors tab in the Properties pane.
򐂰 You look for errors that point to the problem in:
C:\Documents and
Settings\<WindowsAccount>\IBM\RCP\<UNIQUEID>\<username>\logs\SystemErr.log and the
SystemOut.log
3.7.2 Step-by-step: Component test
To test the component, follow these steps:
1. Log in to the Workplace Collaboration Services server.
2. At the Welcome page, select Actions → New Page as shown in Figure 3-50 on page 70.
Chapter 3. Developing the sample application: Basic development topics
69
Figure 3-50 Creating a New Page
3. In Page Properties, name the page as you wish and click OK.
4. When you receive a message that says that the page was created successfully, click OK.
5. On the Edit Layout page, click Add Portlet.
6. On the next page, search for the status report component that you deployed
(Figure 3-51).
7. Select StatusReport and click OK.
Figure 3-51 Adding a portlet
8. Click Done on the Add Portlet page.
You should now see the view that you created. You should also be able to create a new status
report as illustrated in Figure 3-52 on page 71 and Figure 3-53 on page 71.
70
IBM Workplace 2.5 Development with Workplace Designer
Figure 3-52 AllStatusReports view in browser
After the user clicks Create, a new status report is created as shown in Figure 3-53.
Figure 3-53 StatusReportEdit form in browser
Chapter 3. Developing the sample application: Basic development topics
71
72
IBM Workplace 2.5 Development with Workplace Designer
4
Chapter 4.
Developing the sample
application: Intermediate
development topics
In this chapter, we expand upon the application developed in the previous chapter and add
additional features and functionality.
This chapter makes use of the following technologies:
򐂰
򐂰
򐂰
򐂰
򐂰
Response documents
Workflow
Filtered views
Document security
Roles
© Copyright IBM Corp. 2005. All rights reserved.
73
4.1 Response documents
In this section, you learn how to enhance your application to support tasks, namely specific
activities that provide an overview of all the related jobs of a status report. An author is able to
create several tasks for a status report and assign each task with a category, a due date, a
description, and percent complete information. Combined with security and workflow features
that are introduced in the following sections, this data about tasks allows the author and the
author’s manager to have a better understanding of the progress of an activity.
From a technical point of view, tasks are implemented as response documents. These are
documents that are associated to a main document such as our status report document. The
parent and response documents are linked by unique parent and response IDs. Because task
data is stored in its own document, a task form and an associated task schema are required.
Note: There is tight relationship between parent and response documents. In contrast to
Domino behavior, if somebody deletes a main document in the Workplace component, all
of its responses are automatically deleted, too.
To display the tasks, we embedded a view UI control in our StatusReportEdit form. A view UI
control displays a list of documents in a database after a query. Depending on the selection
criteria, you can display all documents of a database or a subset. The documents can be
grouped or sorted based on their contents.
The following list provides you with the steps we discuss in detail in this section. Because
some of these activities were already discussed in previous chapters, we focus on new topics:
1.
2.
3.
4.
Create a task schema that defines the task data.
Create a task form that enables users to create new tasks.
Embed a view to the StatusReportEdit form to display the task response documents.
Add buttons to the form to edit and delete a task.
4.1.1 Step-by-step: Adding a task view to the status report
In this section, you learn how to create an embedded view in your StatusReportEdit form.
Creating a new task schema
To create a new task schema, follow these steps:
1. Create a new schema named task. See 3.2, “Creating a schema” on page 32 for detailed
information about this topic.
2. Add the child elements listed in Table 4-1 to the task schema.
Table 4-1 Elements for the task schema
Element name
Data type
category
string
subCategory
string
dueDate
date
taskCompletion
integer
description
string
You can see the elements that you added in the Visual Editor (Figure 4-1 on page 75).
74
IBM Workplace 2.5 Development with Workplace Designer
Figure 4-1 Schema for task
3. Save and close the new schema.
Creating the task form
To create the task form, follow this procedure:
1. Create a new form called TaskEdit, which uses the task schema. See 3.3, “Creating a
form” on page 37 for detailed steps.
2. Create a table and nested table. Adding a nested table to the form makes it easier to
arrange the UI controls and their labels in the form. Furthermore, using the Format tab of
the table, you can customize the style of the columns and rows. Refer to Figure 4-3 on
page 76 to see how the table should look.
3. Add the Category, Sub-Category, Due Date, and Percent Completed edit boxes and their
corresponding labels to the table. For the Description UI control, use a Multiline Edit Box
that expands to the full width of the table. Add a computed field at the top of the form that
displays Task as the name of the document. Remember to bind the UI controls to the
corresponding elements of the task schema defined in Table 4-1 on page 74. Refer to
Figure 4-3 on page 76 to see how we arranged the controls.
Note: Instead of using a computed field to display the title of the form (Task), you can
apply a label UI control with a computed label option.
4. To ensure that the Percent Completed edit box only accepts values from 0 to 100, you set
validation for this UI control. Figure 4-2 shows the section. Refer to 3.6, “Data validation”
on page 65 if you need more information about validation. Do not check Required field.
Figure 4-2 Setting validation to the Percent Completed edit box
5. Add an Edit Task, a Save, and a Cancel button to the form and set the corresponding
Visible properties. Assign the buttons to simple button types. Arrange the buttons as
shown in Figure 4-3 on page 76.
Chapter 4. Developing the sample application: Intermediate development topics
75
Figure 4-3 The TaskEdit form
6. Provide the Edit Task button with a simple action that changes the document mode. Make
sure that this simple action executes as an onClick event.
Tip: If you accidentally deleted a button or a field, you can undo your last action by
pressing Ctrl+Z. The Script Editor supports the undo feature, too.
7. Now you must add navigation code to the Save and Cancel buttons. This is because you
want to make sure that users are returned to the parent Status Report document in edit
mode after they close the saved Task document. Because these are general functions that
might be used in other areas, we decided to put this code in a script library.
To do this, create a new script library named NavigationScripts and copy the functions of
Example 4-1 on page 77 and Example 4-2 on page 77 into it. For more information about
Script Libraries refer to “Creating a script library” on page 50.
76
IBM Workplace 2.5 Development with Workplace Designer
Example 4-1 JavaScript to return to the parent document
function openParentDocument(document, context, destination, autoedit) {
var url = new XSPUrl("");
url.setAddress(destination);
if (document.hasParent()) url.setParameter("id", document.getParentId());
url.setParameter("action", "openDocument");
url.setParameter("autoedit", autoedit);
context.redirectUrlOnServer(url.toString());
}
Example 4-2 JavaScript to save and return to the parent document
function saveCurrentDocumentEdit(document, context, destination) {
if (document.isEditable()) document.save();
openParentDocument(document,context,destination,"true");
}
The openParentDocument function uses the XSPUrl class to build a new URL and to set
the necessary parameters. In our example, we accessed the parent Status Report
(destination) document using the parentid parameter and opened (openDocument) it in
edit mode (autoedit=true). See Table 4-2 for a list of parameters that can be manipulated
by methods in XSPUrl. The method redirectUrlOnServer of the XSPContext class then
uses this page to answer the client without sending a client redirect message. For more
information about using these classes refer to the Workplace Designer Help.
Table 4-2 URL parameters to set through methods of the XSPUrl class
Parameter
Description
action
This may be openDocument or newDocument.
database
This is the name of the database, typically the
same as the component name.
schema
This is the name of the schema.
id
This is the document ID, necessary for
openDocument but omitted for newDocument.
parentid
The ID of the parent document.
autoedit
This can be true or false.
Tip: The Workplace Designer Help features multiple topics and also discusses Workplace
Collaboration Services and IBM Productivity Tools. Thus, a full text search could return a
significant amount of search results. It helps if you define a search scope to show only
topics for Workplace Designer and Workplace Designer Reference.
8. Edit the onClick event for the Save button so that it has the code in Example 4-3.
Example 4-3 JavaScript for Save button
import NavigationScripts;
saveCurrentDocumentEdit(document, context, "StatusReportEdit.xsp");
Chapter 4. Developing the sample application: Intermediate development topics
77
Tip: The Reference tab of the Script Editor lists the available global objects and system
packages (libraries) that provide a starting point for server-side scripting. For example,
we used the document object in the Save button as a starting point for obtaining the
parent ID for the current document. The global objects in Table 4-3 provide a starting
point for server-side scripting.
Table 4-3 Global objects
Global variable name
Description
session
A DBSession object representing the connection to the document
server
sessionData
A global variable for the user session; implemented as a standard
JavaScript object
pageData
A global variable available during the page processing; implemented
as a standard JavaScript object
database
A DBDatabase object representing the database being accessed
upon script invocation
document
A DBDocument object representing the form or other artifact being
processed upon script invocation
context
A global object that provides access to the database server, the user
browser, and other objects
9. Add the code in Example 4-4 to the onClick event for the Cancel button.
Example 4-4 JavaScript for Cancel button
import NavigationScripts;
openParentDocument(document, context, "StatusReportEdit.xsp","true");
Note: Because you are using server-side JavaScript libraries here (for example, DocDB),
you must choose Run on server for the onClick event. For more information about using
server-side scripts refer to the Workplace Designer Help.
10.Save and close the TaskEdit form.
Embedding a view in the form
After creating the TaskEdit form to display and store the task data, you can embed a view in
the StatusReportEdit form that shows all task documents of a status report as follows:
1. Open the StatusReportEdit form.
2. Position your cursor below the first table and create another table with one column and two
rows in which you can insert your task view. Refer to Figure 4-4 on page 79 to see what
the table looks like.
3. The first row shows the title of this view. Add a computed field with the string value Tasks
to it.
4. Add a view from the Container Controls pane to the second row by following the
instructions in 3.5.1, “Views versus view controls” on page 51.
5. Because you only want task response documents in this view, assign the task schema in
the Data tab of the view. Select Show all results as shown in Figure 4-4 on page 79.
78
IBM Workplace 2.5 Development with Workplace Designer
6. To have a view navigator for this view, assign it using the Basics tab.
Note: The Basics and Data panes are tabs for the Properties pane of the view. It opens
below the canvas after you click the outer frame of the view.
Figure 4-4 Creating an embedded task view
7. Add five columns to the view and bind them to the these schema elements: category,
subCategory, description, dueDate, and taskCompletion. Remember to label the columns.
Note: Because you have assigned the task schema to the view, you are able to bind the
corresponding schema elements to the columns.
8. Because dueDate is not a mandatory field in the task document, the content of this field
should only be shown if it contains a value. Add the code in Example 4-5 to the formula for
the dueDate column.
Example 4-5 JavaScript code returns a date string value
var dueDate = document.getDateValue("/task/dueDate");
if ((dueDate == null) || (dueDate.toString().equals("")))
return "";
else
return dueDate.toDateString();
9. In the Formula field of the taskCompletion column, add the code in Example 4-6 on
page 80 to display a percent character (%) next to the value in the column.
Chapter 4. Developing the sample application: Intermediate development topics
79
Example 4-6 JavaScript for the taskCompletion column
document.getIntValue("/task/taskCompletion").toString()+"%";
10.Modify the properties of the category column so that users can mark multiple tasks for
deletion and click the value of the category column to open a task for reading. You find
these options in the Basics tab of the column, namely, Add the checkbox and Show
value in the column as links.
11.Save the StatusReportEdit form.
One basic feature is still missing in the response view logic. Right now, this view would show
all task documents that exist in the database of our application. Because you only want to
show the tasks of the current status report, you must add more response logic to the view.
Adding response logic
Because task documents are the response documents for a status report, you filter the view
to show only documents where the parent ID for the task matches the document ID of the
current status report as follows:
1. Add a hidden column to the task view to display the parent ID of a task:
a. Hide this column by setting the Visible option of the Basics tab to False.
b. Edit the formula of the column so that it has the code in Example 4-7. Be aware of the
name of the hidden column because we refer to it in the next step. You can select this
name in the Basics tab for the column.
Example 4-7 JavaScript for the hidden column in the task view
document.getParentId();
2. Open the Sort/Filter tab of the Properties pane for the task view.
3. Select Show items meeting the following dynamic conditions and enter the code from
Example 4-8 to display only documents. In the code, the value of the hidden column
(which is the parent ID of the task document) matches the Status Report document ID.
Notice that column_3 is the name of the hidden column that you created in step 1.
Example 4-8 JavaScript for filtering the task view
"column_3 = \"" + document.getId() + "\"";
Figure 4-5 Sort/Filter tab of the task view
4. Save the StatusReportEdit form.
For more information about filtering views refer to 5.4, “Advanced filtering” on page 131.
80
IBM Workplace 2.5 Development with Workplace Designer
Adding buttons to the task view
To create a new task, a button on the StatusReportEdit form is required. Also, we want to add
a button to delete selected tasks.
Follow these steps to create the buttons for the task view:
1. Add a New Task... and a Delete Tasks button above the task view.
2. The New Task... button performs two actions. First, it saves the current status report
document. Then, it creates a new task response document. Utilizing the XSPUrl class,
build a new URL and set the necessary parameters. The method redirectUrlOnServer of
the XSPContext class then uses this page to answer the client without sending a client
redirect message. For more information about using these classes refer to the Workplace
Designer Help.
In our example, we opened a new task document (destination) in edit mode and
assigned the Status Reports document ID to the parent ID (parentid) parameter. Add the
function in Example 4-9 to your Navigation Scripts library.
Example 4-9 JavaScript code creates a new response document
function openNewResponseDocument(document, context, destination) {
var url = new XSPUrl("");
url.setParameter("parentid", document.getId());
url.setParameter("action", "newDocument");
url.setParameter("autoedit", "true");
url.setAddress(destination);
context.redirectUrlOnServer(url.toString());
}
3. Edit the onClick event for the New Task... button so that it has the code in Example 4-10.
Example 4-10 JavaScript of the New Task... button
import NavigationScripts;
document.save();
openNewResponseDocument(document, context, "TaskEdit.xsp");
4. Add a simple action such as an onClick event to the Delete Tasks button, which deletes
the selected task documents from the embedded task view. Make sure that you match the
name of the view in the simple action to the task view that you created.
5. Save and close the StatusReportEdit form.
Now users are able to create, modify, and view tasks in their own status reports.
4.2 Optional: Dynamic combo boxes
In this section, we look at how to create server-side JavaScript that takes documents that are
created by a form and exposes them as options in the combo box UI control. By creating this
on the server side, it is not necessary to send the client all the options with functions to limit
their choices.
In this section, we also make use of page-persistent data captured in the pageData object.
Page-persistent data is a methodology that allows you to save values temporarily based on
the results of one object on the page and makes that value available to another object on the
page. Data that is saved in the pageData component is valid only while the user is on the
page.
Chapter 4. Developing the sample application: Intermediate development topics
81
If you would like to reference data for a greater duration than a page, you can use
session-persistent data with the sessionData object. This operates in much the same way as
the pageData object except that the data is valid for the life of the session. The sessionData
object is not the subject of this section, but it is used in a later part of this paper.
Design idea: While we do not use such methods in this paper, you could limit the choices
in a combo box based on the user’s document level access, because you are using actual
views and documents to pull the choices. Document level security is further discussed in
4.5, “Document level security” on page 99.
4.2.1 Step-by-step: Creating the dynamic combo box
To make the combo box, you create a new schema element, a new form, and modify the
TaskEdit form to use these new categories. In addition, you create a new view to manage all
the categories and expand the main page to access the new view.
Creating new schema elements
To create new schema elements, follow these steps:
1. Create a new schema named category. (See 3.2, “Creating a schema” on page 32 for
detailed instructions.)
2. Add two child elements, prime and sub, both with a string type, and select A value must
be specified for both.
3. Save and close the new schema.
Creating the category form
To create the new category form, follow these steps:
1. Create a new form named CategoryEdit, which uses the category schema that you
created. (See 3.3, “Creating a form” on page 37 for detailed instructions.)
2. In this form, you create two edit boxes, two buttons, and labels as shown in Figure 4-6.
Figure 4-6 CategoryTask layout
3. Make sure that the Save button is the Submit type and make the Cancel button a Cancel
type with an onClick simple action that sends the user back to the AllCategories form.
4. Bind the edit box for the Category Name field to the prime schema element, and bind the
edit box for the Sub-categories field to the sub schema element.
82
IBM Workplace 2.5 Development with Workplace Designer
5. Both fields are automatically required because you set the schema up this way, so make
sure you type an error message for Required field error message.
Because the sub-category edit box is implemented with one line, it is important to inform
users that they should use a comma to separate the entries. You can do this with an
on-screen instruction as follows:
1. Enter a blank line between the Sub-categories label and the corresponding edit box.
2. Click Image in the UI Controls panel and click a place in the blank line that you created.
3. Click Add Image....
4. Use an icon of your choice or use speechbubble.jpg (Figure 4-7) located at:
<InstallFolder>\applications\eclipse\plugins\com.ibm.workplace.designer.sampleApps_1.0.0
\sampleApps\SampleImages\SpeechBubble.jpg
Figure 4-7 Add Image dialog
5. Click OK.
6. Select the newly imported image and click OK.
7. With the speech button on the form, create a label next to it with the text Please enter
sub-categories below (comma delimited).
The form resembles that in Figure 4-8.
Figure 4-8 CategoryEdit final layout
Chapter 4. Developing the sample application: Intermediate development topics
83
Design idea: You can add more tips at any point in the application where you believe a
user might need more information. For example, you could add tips for the Lookup button,
so that users realize that they must click it after typing in a manager’s name.
8. Save and close the form.
Creating a category view
Creating a category view has the following procedure:
1. Create a new form called AllCategories.
2. In the form, create three buttons (New, Delete, Done), a label, and a two-column view. The
result is shown in Figure 4-9.
Figure 4-9 AllCategories Layout
3. Change the name of the first column to col_prime and the second to col_sub. You use
these columns later.
4. Change the name of the view to primeCatView.
5. For the New button, set the onClick event to create a new CategoryEdit document.
6. For the Delete button, set the onClick event to delete the selected documents. Make sure
that you choose the view that matches the one that was created for this form.
7. From the Data tab of the Properties pane for the view, choose the category schema.
8. Click the first column of the view. Set the Basic properties to have check boxes and select
Show values in this column as links with the Edit option chosen.
9. In the Data tab for the same column, choose prime for the Data field option.
10.For the second column, choose the sub for the Data field option.
11.For the Done button, change the Button type to Submit.
12.Go to the Properties panel for the form. Change Next page (successful update) to Other
page and use the AllStatusReports form.
13.Save and close this form.
84
IBM Workplace 2.5 Development with Workplace Designer
14.Open the CategoryEdit form. Change Next page (successful update) to AllCategories.
Modifying the task form
To modify the task form, follow this process:
1. Open the TaskEdit form.
2. Replace the Category and Sub-Category edit boxes with combo boxes.
3. From the Values tab for the Category combo box, change Create Selection to From
formula.
4. Select Insert text row at top of Combo box and put -Please Select One- in the Label.
5. In the JavaScript editor, add the code from Example 4-11.
Example 4-11 JavaScript for Category combo box value
var catview = database.openView("primeCatView");
var catValues = catview.getColumnsValues("col_prime");
return catValues;
6. From the Data tab, change Data binding so that it points to the category element.
7. From the Events tab, enter the code in Example 4-12 in the onChange event.
Example 4-12 JavaScript for onChange event for Category combo box
pageData.cat1 = document.getStringValue("/task/category");
8. Repeat steps 3, 4, and 5 for the Sub-Category combo box, but use the JavaScript code in
Example 4-13.
Note: To make sure the Properties pane is completely refreshed when you are moving
between combo-boxes, click a different kind of element, such as a blank space in the
form.
Example 4-13 JavaScript for Sub-Category combo box value
var category1 : String;
if (!(document.getStringValue("/task/category").isEmpty()))
pageData.cat1 = document.getStringValue("/task/category");
category1 = pageData.cat1;
if ((category1 == null) || (category1 == ""))
return "";
var catview = database.openView("primeCatView");
var tmpresults : String;
var tmpresults = catview.getLookupValue(category1,"col_sub");
var results = new Array();
while(!tmpresults.isEmpty()){
i = tmpresults.indexOf(",");
if (i < 0){
results.push(tmpresults);
tmpresults = "";
}
else {
results.push(tmpresults.substring(0,i));
tmpresults = tmpresults.substring(i+1);
}
}
return results;
Chapter 4. Developing the sample application: Intermediate development topics
85
9. Change Data binding for the Sub-Category combo box to point to the subcategory
element.
10.Figure 4-10 shows the results. Save and close the form.
Figure 4-10 TaskEdit form with comboboxes
Finishing touch needed on the main page
For the finishing touch on the main page, follow these steps:
1. Open the AllStatusReports form.
2. Create a button at the top of the form that is labeled Manage Task Categories.
3. Change the onClick event for the button to a simple action that opens a form (Open a
form) and targets the AllCategories form as a New Document in Edit Mode.
4. Figure 4-11 shows the expected results. Save and close the form.
Figure 4-11 AllStatusReports with Manage Task Categories button
86
IBM Workplace 2.5 Development with Workplace Designer
4.3 Adding workflow
At this point, you have created a more functional version of the status report application, but it
can be improved to move the reports through various states. For example, if a user wants to
start a report, but does not have all the information at that time, a flag that lets others know
that the report is still in draft would be helpful. Also, managers might find it useful to make
sure that after a status report is created and submitted, it cannot be edited again. This
prevents users from changing the state.
For our application, we decided to use three states. The first is draft, in which all documents
are created. The idea is that a user can save the document in draft. The second is current;
after completion, the user can submit the document so that the manager can see that it is
current. The final is an archived state that documents can be moved to after a new report is
created that supersedes the existing one or when the report is no longer necessary.
Draft
Current
Archived
Figure 4-12 Workflow states
When implementing the multiple states of the document, you use a field that stores a number
that represents one of the above states. Table 4-4 shows the ID and the represented status.
Table 4-4 ID status reference table
ID Number
State
1
Draft
2
Current
3
Archived
4.3.1 Step-by-step: Building in workflow
To add workflow to the application, you add the idea of a state to the StatusReport form and
change the buttons to provide the workflow to switch a document between states.
Adding state information to the form
The instructions for adding state information to the form are:
1. Create two new string elements in the statusReport schema, status and history.
2. Open the StatusReportEdit form.
3. Expand the table by adding a new row after the Manager row.
4. Add the label called Status and a computed field as shown in Figure 4-13 on page 88.
5. Click the new computed field and, for the value, use the JavaScript from Example 4-14 on
page 88.
Chapter 4. Developing the sample application: Intermediate development topics
87
Example 4-14 JavaScript code for Status computed field
var retStatus = document.getStringValue("/statusReport/status");
switch (retStatus){
case "1" :
"Draft";
break;
case "2" :
"Current";
break;
case "3" :
"Archived";
break;
}
6. Add another row under the Summary field.
7. Add the History label and create a multi-line edit box as shown in Figure 4-13. History
tracks the changes to a status report as they go through multiple states.
Figure 4-13 StatusReportEdit with Status and History Fields
8. Bind the edit box to the history schema element and make it read-only.
9. The history should only appear when there is one, so change the Visible property for the
History label and edit box by using the code shown in Example 4-15.
Example 4-15 Visible code for History label and edit box
document.getStringValue("/statusReport/history")!="";
Modifying the default action for new documents
Append the code from Example 4-16 on page 89 to the onPostNewDocument for the form.
This sets the status field to a default value and copies a summary from a previous report into
the history field for the new document.
88
IBM Workplace 2.5 Development with Workplace Designer
Example 4-16 Additional code for onPostNewDocument
// set the default status
document.setStringValue("/statusReport/status","1");
// set the history field
var sourceDocId = context.getUrlParameter("sourceDocId");
var historyLine : String;
var curHistory : String;
var curSummary : String;
if (sourceDocId != "") {
var curDB = document.getDatabase();
var sourceDoc = curDB.getDocumentById(sourceDocId);
curSummary = sourceDoc.getStringValue("/statusReport/summary");
if (curSummary!=""){
historyLine = sourceDoc.getDateValue("/statusReport/date").toDateString() + ":
"+curSummary;
}else{
historyLine = "";
}
curHistory = sourceDoc.getStringValue("/statusReport/history");
if (curHistory!=""){
if (historyLine!=""){
setFieldValue("history", curHistory+@NewLine()+historyLine);
} else {
setFieldValue("history", curHistory);
}
} else {
if (historyLine!="") setFieldValue("history", historyLine);
}
}
Adding and changing buttons based on state
To add and change buttons based on state, follow these steps:
1. Open the StatusReportEdit form.
2. Create four new buttons at the top of the form with the following labels: Save Draft, Delete,
Update, and Archive as shown in Figure 4-14.
Figure 4-14 StatusReportEdit with workflow buttons
3. For the Save Draft button set the properties from Table 4-5 on page 90.
Chapter 4. Developing the sample application: Intermediate development topics
89
Table 4-5 Save Draft button properties
Property
Value
Visible
document.isEditable() &&
document.getStringValue("/statusReport/status") == "1";
Button Type
Submit
4. For the Save & Submit button change the properties to those in Table 4-6.
Table 4-6 Save & Submit button properties
Property
Value
Visible
document.isEditable() &&
document.getStringValue("/statusReport/status") == "1";
onClick Event
import NavigationScripts;
document.setStringValue("/statusReport/status","2");
saveCurrentDocumentEdit(document,context,"AllStatusReports.xsp");
5. For the Delete button, change the properties to match those in Table 4-7, so that users can
only delete draft documents. Also, add the function in Example 4-17 to the Navigation
Scripts library.
Table 4-7 Delete button properties
Property
Value
Visible
!(document.isNewDocument()) &&
document.getStringValue("/statusReport/status") == "1";
onClick event
import NavigationScripts;
deleteCurrentDocument(document, context, "AllStatusReports.xsp");
Example 4-17 Script for deleteCurrentDocument
function deleteCurrentDocument(document, context, destination) {
var url = new XSPUrl("");
if (document.hasParent()) {
url.setParameter("id", document.getParentId());
url.setParameter("action", "openDocument");
url.setParameter("autoedit", "false");
} else {
url.setParameter("action", "newDocument");
}
url.setAddress(destination);
document.remove();
context.redirectUrlOnServer(url.toString());
}
6. For the Update button, change the properties to match those in Table 4-8 on page 91.
Because you want the button to generate a new StatusReportEdit form that can pass the
current summary as the new documents history, you cannot use a simple action. You must
also add the function from Example 4-18 on page 91 to the Navigation Scripts library.
90
IBM Workplace 2.5 Development with Workplace Designer
Table 4-8 Update button properties
Property
Value
Visible
document.getStringValue("/statusReport/status")=="2";
onClick event
import NavigationScripts;
createNewDocument(document, context, "StatusReportEdit.xsp");
Example 4-18 The createNewDocument function for NavigationScripts
function createNewDocument(document, context, destination) {
var url = new XSPUrl("");
url.setParameter("sourceDocId", document.getId());
url.setParameter("action", "newDocument");
url.setParameter("autoedit", "true");
url.setAddress(destination);
context.redirectUrlOnServer(url.toString());
}
7. For the Edit button, change the properties to match those in Table 4-9.
Table 4-9 Edit button properties
Property
Value
Visible
!(document.isEditable()) &&
document.getStringValue("/statusReport/status") == "1";
8. For the Archive button, change the properties to match those in Table 4-10. Add the script
in Example 4-19 to the Navigation Scripts library.
Table 4-10 Archive button properties
Property
Value
Visible
document.getStringValue("/statusReport/status")=="2";
Button type
Submit
onClick
import NavigationScripts;
document.setStringValue("/statusReport/status","3");
document.save();
openView(document,context,"AllStatusReports.xsp");
Example 4-19 The openView function for NavigationScripts
function openView(document:DBDocument, context, view) {
var url = new XSPUrl("");
url.setAddress(view);
context.redirectUrlOnServer(url.toString());
}
4.4 Simple filters
In this section, you learn how to filter data in views, depending on the column values. You can
change your view in the AllStatusReports form that you created when you followed the
instructions in 3.5, “Creating a view” on page 51. Then, you can create three copies of this
view, where each displays documents that are relevant to each of the status types.
Chapter 4. Developing the sample application: Intermediate development topics
91
Preparing for filtering
Expand the AllStatusReports view by adding one more column that displays the actual
workflow status of documents. The outline of the new view is shown in Figure 4-15.
Figure 4-15 Extended All Status Reports view
The workflow status is stored in documents as a number (for example, 1 or 3). The computed
column translates this number to its text representation (for example, Draft or Archived).
The next step is to add a new computed column to the AllStatusReports view. The purpose of
the column is to display the Workflow status of a document. You filter your view by this
column.
Adding an advanced computed column
To add an advanced computed column, follow these steps:
1. Open the AllStatusReports form.
1. Inside the All status reports view, right-click the column called View and choose Insert
column (this inserts a new column before the View column, as shown in Figure 4-16).
2. Click the header, go to the Properties pane, and change the Label to Status.
Figure 4-16 All status reports view with Status column
3. This column is going to be a computed column, so click the Data tab and change the Data
field option to Formula.
4. Click Script Editor and type the JavaScript code shown in Example 4-20 on page 93.
Click OK.
92
IBM Workplace 2.5 Development with Workplace Designer
Example 4-20 Status column computed formula
switch (document.getStringValue("statusReport/status")) {
case "1": return "Draft";
case "2": return "Current";
case "3": return "Archived";
}
Tip: You can also write the code in Example 4-20 using @Functions:
status = @GetTextField("status");
@If(status == "1", "Draft", status == "2", "Current", status == "3", "Archived", "")
Testing your component (optional)
If you want to make sure that the code is working properly, you can test your component at
this check point as follows (this is optional):
1. Save your form by clicking File → Save.
2. Click anywhere in your component in the Component Navigator.
3. In the main menu, select File → Component → Deploy... and in the Deployment
Component dialog (Figure 4-17), click OK.
Figure 4-17 Deploy Component dialog
4. Open your Web browser and navigate to your portlet, which should look like Figure 4-18.
Figure 4-18 AllStatusReports form
Multiplicating views
So that you can set different filters, you must create three copies of this view as shown in
Figure 4-19 on page 94.
Chapter 4. Developing the sample application: Intermediate development topics
93
Figure 4-19 Multiplicating views
1. Open the AllStatusReports form, highlight the All Status Reports label, and change the
text to Drafts.
2. Create the first copy:
a. Highlight the All Status Reports label and choose Edit → Copy from the main menu.
b. Go to the end of the form and choose Edit → Paste. Change the text to Current status
reports.
c. Highlight the Drafts view on the form and select Edit → Copy from the main menu.
d. Return to the end of the form and select Edit → Paste.
Figure 4-20 Copy of the Drafts view
3. Create the second copy the same way, but change the name of the newly created label to
Archive.
94
IBM Workplace 2.5 Development with Workplace Designer
Tip: When you copy a whole view control and paste it in a form, the column headers are
renamed to the default columnHeader_xx labels as illustrated in Figure 4-20. This is
because columns, even when they are copied and pasted, must have unique names.
However, it is possible to copy and paste a whole view control including view header labels:
1. Highlight a whole view control, copy, and then paste it in a form.
2. In the newly created view, delete all the columns one-by-one. (Do not worry if your view
control shrinks to a small rectangular box. This is because the width and height
properties are set to Auto.)
3. Return to the original view and select all of the view columns. (You can use the Shift key
to select multiple columns, or you can just drag a selection with your mouse.) From the
main menu, choose Edit → Copy.
4. Now, click the newly created view and click Edit → Paste.
Defining filters with the Query Editor
The Query Editor is a simple interface for defining view selection criteria. You can use it to
visually define a complex selection formula and specify what column must or must not be
equal to a value, what column must be less or greater than a given value, or a combination of
these conditions.
We demonstrate the Query Editor in the Drafts view control (see Figure 4-21).
Figure 4-21 Defining selection criteria on the Drafts view
The step-by-step instructions for using the Query Editor are:
1. Click the Drafts view:
a. Select the Status column.
b. In the Properties pane on the Basic tab, the column has a name (for example,
column_8). Remember this name.
c. Highlight the whole Drafts view (by clicking somewhere in its border).
d. From the Properties pane, choose Data and change the Selection mode from Show all
results to Show results matching the following conditions.
Chapter 4. Developing the sample application: Intermediate development topics
95
e. Select Dynamic conditions based on column values (Figure 4-22).
Figure 4-22 Add dynamic conditions based on column values
f. To add the filter to the view, click Edit.
g. In the Query Editor (Figure 4-23), follow these instructions:
i. Leave Function unchanged (None).
ii. Set Column to the name from step 2 (for example, column_8).
iii. Set Operator to the symbol for “equals” (=).
iv. In the Value field, type:
"Draft"
You must include the quotes, which are very important.
v. Click Insert and click OK.
Figure 4-23 Using the Query Editor
Defining filters using JavaScript
This section shows you how to define view selection criteria with JavaScript. This method is
an alternative to column value filtering. The JavaScript method is more powerful, because you
can use data fields other than those that are propagated in columns.
96
IBM Workplace 2.5 Development with Workplace Designer
Note: The example discussed in this section is an alternative to that discussed in “Defining
filters with the Query Editor” on page 95. Everything defined for this example with
JavaScript can also be defined with the Query Editor. The results of both methods are, in
this case, identical.
In this section, you learn how to use Javascript to define filters for the Current and Archived
views (Figure 4-24).
Figure 4-24 Defining selection criteria in Current and Archived views
The steps for using JavaScript selection formulas are as follows:
1. Click the Current Reports view.
a. In the Properties pane, choose Data. Change the Selection mode from Show all
results to Show results matching the following conditions.
b. Select Static JavaScript conditions.
c. Click the Edit button, which has become available to the right of the field (Figure 4-25).
Figure 4-25 Adding static JavaScript conditions
Chapter 4. Developing the sample application: Intermediate development topics
97
d. In the Script Editor, enter the code shown in Example 4-21.
Example 4-21 JavaScript selection formula for documents in Current status
document.getStringValue("statusReport/status") == "1"
Tip: You can write the code shown in Example 4-21 using @Functions:
@GetTextField("status") == "1"
e. When you are finished, click OK.
2. Click the Archives view and repeat step 1, but use the code shown in Example 4-22.
Example 4-22 JavaScript selection formula for documents in Archived status
document.getStringValue("statusReport/status") == "2"
Consolidating views
Because only draft documents can be edited or deleted, it is a good idea to delete Edit
columns and check boxes where they do not make sense. To achieve a similar graphical look,
you can also delete View columns where Edit column is enabled. See Figure 4-26 for an
illustrated overview.
Figure 4-26 Consolidating views
1.
2.
3.
4.
5.
Right-click the View column in the Drafts view and click Delete.
Right-click the Edit column in the Current Status Reports view and click Delete.
Click the check box column in the same view and clear Check box.
Right-click the Edit column in the Archives view and click Delete.
Click the check-box in the same view and clear Check box.
Testing your form (optional)
You can test your form as follows:
1. Save your form by selecting File → Save.
2. Click a place in your component in the Component Navigator.
98
IBM Workplace 2.5 Development with Workplace Designer
3. From the main menu, select File → Component → Deploy..., and in the Deploy
Component dialog (Figure 4-27), click OK.
Figure 4-27 Deploy Component
4. Open your Web browser and navigate to your portlet, which should resemble Figure 4-28.
Figure 4-28 AllStatusReports form
4.5 Document level security
When you add drafts and views that allow users to see the various states of a document,
security becomes an issue. In other words, it is advisable to add some level of security.
Otherwise, all the documents that are created in a portlet can be seen by all the other users
that decide to use the same component. To prevent this, you can implement the readers and
editors feature on a per document basis. A Readers field provides a list of users that are only
allowed to read a given document. An Editors field provides a list of users that are allowed to
edit a given document. If either of these fields are blank, then there is no restriction for the
given action.
Based on the workflow features that have been added to the application, we want the
application to work in such a way that, if a document is in draft mode, only the person that
created it can see and edit it. Then, when the document is submitted, the manager that is
identified in the form can be added as a person that can see the document. Up to this point, it
has not been a requirement that the manager actually be resolved by the lookup. However,
now that you are going to add the manager to the Readers field, you modify the Save buttons
so that they only submit data after a successful lookup provides the manager’s information.
Chapter 4. Developing the sample application: Intermediate development topics
99
Design Idea: You can further restrict access so that users cannot edit their own document
after they have submitted it by removing them from the Editors field at the time they submit.
In our example, we do not do this, so, while the user cannot see a button that puts a
document in edit mode, it could be done by direct manipulation of the URL.
4.5.1 Step-by-step: Adding security
To add security to the application, you modify the events that fire when a new document is
created and change the existing buttons so that they can add and remove users from the
Readers and Editors fields. You can also can add features to help you debug the state of the
application fields. You do not have to modify your views because the document level access is
checked during the process of determining which documents a user sees in a view.
Modifying new document defaults
To modify new document defaults, open the StatusReportEdit form, and proceed as follows:
1. Go to the Events tab in the Properties panel for the form.
2. Modify the existing onPostNewDocument by appending the code in Example 4-23.
Example 4-23 JavaScript to add to the onPostNewDocument
// give the owner of the status report reader/editor access
editors = document.getEditors();
readers = document.getReaders();
statusReportOwner=new Array(currentDn);
editors.setFieldValues("statusReportEditors",statusReportOwner);
readers.setFieldValues("statusReportReaders",statusReportOwner);
3. Save the form.
Modifying your buttons
Open the StatusReportEdit form (if it is closed) and proceed as follows:
1. Change the code for the onClick event of the Save & Submit button to match the code in
Example 4-24.
Example 4-24 Updated Save & Submit Button
import NavigationScripts;
var mgrEmail = document.getStringValue("/statusReport/managerEmail");
if (mgrEmail!="") {
var manager = document.getStringValue("/statusReport/manager");
readers = document.getReaders();
if (manager != "") {
readers.add("statusReportReaders",manager);
}
document.setStringValue("/statusReport/status","2");
pageData.hasSearchFailed = false;
saveCurrentDocumentEdit(document,context,"AllStatusReports.xsp");
} else {
pageData.hasSearchFailed = true;
};
2. Change the code for the onClick event of the Archive button to match the code in
Example 4-25 on page 101.
100
IBM Workplace 2.5 Development with Workplace Designer
Example 4-25 Updated Archive button
import NavigationScripts;
readers = document.getReaders();
editors = document.getEditors();
var manager = document.getStringValue("/statusReport/manager");
var noAccess=new Array(" ");
editors.setFieldValues("statusReportEditors",noAccess);
if (readers.contains(manager)==false && manager != "") {
readers.add("statusReportReaders",manager);
}
document.setStringValue("/statusReport/status","3");
document.save();
openView(document,context,"AllStatusReports.xsp");
3. Save the form.
Simplifying debugging (optional)
Open the StatusReportEdit form and proceed as follows:
1. Create a table at the bottom of the form with two columns and two rows.
2. Add two labels and two computed fields as shown in Figure 4-29.
Figure 4-29 Debug fields at bottom of StatusReportEdit
3. For the computed field called Readers, add the code in Example 4-26 to the Value field.
Example 4-26 Computed value for Readers debug edit box
document.getReaders();
4. For the Editors field, add the code in Example 4-27 on page 102 to the Value.
Chapter 4. Developing the sample application: Intermediate development topics
101
Example 4-27 Computed Value of Editors debug edit box
document.getEditors();
5. Because this is a table, you can change the visibility of the table as a whole after you have
completed the debugging.
4.6 Applying roles
Having security at a document level is helpful, but there is no real personalization of the user
experience in the Workplace Collaboration Services environment. In the current state of the
application, the team member and the manager can see all the same views, although
managers can see more documents because they are in the Readers and Editors fields for all
users that they manage. Such a layout, while usable, is not the best design because
managers are now getting views, such as draft, that they do not need to see, and most likely
would be blank.
When you begin using roles as an integral part of the application, you must start using the
component as a portlet in a template to make use of them. For example, we have certain
features such as the Manage Task Categories that only appear for those who are managers.
This makes the button invisible until the template is rolled into an application and the roles
have been mapped.
Workplace Designer has five different roles:
򐂰
򐂰
򐂰
򐂰
򐂰
No access
Author
Reader
Editor
Administrator
For our application, we decided to focus on using two roles, Author and Administrator. The
normal team member was mapped to the Author role so that the Author can create new
documents, and the manager is the administrator for the team.
4.6.1 Step-by-step: Using roles
In this section, you learn how to map user roles so that views and buttons displayed are
based on what kind of user is opening the component.
Modifying buttons
1. Open the PersonalizedStatusReports view and click Manage Task Categories.
2. Change the Visible property of the button to match the code in Example 4-28.
Example 4-28 Visible property for Manage Task Categories button
import UtilityScripts;
return hasRole("Administrator");
3. Because hasRole is a new function, put the code in Example 4-29 on page 103 in the
UtilityScripts library.
102
IBM Workplace 2.5 Development with Workplace Designer
Example 4-29 hasRole function for UtilityScripts library
function hasRole(role:String){
var user = context.getUser();
var roleList = user.getRoles();
for (r in roleList){
if (r.equals(role))
return true;
}
return false;
}
4. Save the form.
Modifying views
The views that you created in the previous sections apply to simple users who create and edit
their own status reports (not managers). In this section, you learn how to create two new
views intended only for managers, and hide them for other users. Managers have the
Administrator role, so whether to show or hide these views depends on if a user has the
Administrator role or not. You also learn how to hide the remaining views from earlier
processes for managers, because managers now have their own views. Figure 4-30
illustrates the plan.
Figure 4-30 Creating manager’s view
Merging the Current and Archived views
Open the AllStatusReports form and proceed as follows:
1. Create a new Table control above the one that is already on the form.
Chapter 4. Developing the sample application: Intermediate development topics
103
2. Because you are going to use only one cell:
a. Highlight the last two columns. From the main menu, select Element → Table →
Delete columns... and enter two columns to delete.
b. Highlight the last row. From the main menu, select Element → Table → Delete rows...
and specify one row to delete.
Tip: The reason you are putting the new view in a separate table is because this is the
most effective way to show or hide multiple controls in a form with one formula.
3. Copy the label as follows:
a. Right-click the Drafts label and choose Copy.
b. Right-click anywhere in the newly created row in the table and choose Paste.
c. In the Basic tab of the Properties pane, change the Label to Status reports by users.
4. Duplicate the Current Reports view as follows:
a. Right-click the entire Current Reports view and choose Copy.
b. Right-click anywhere in the newly created row in the table and choose Paste as shown
in Figure 4-31 and Figure 4-32 on page 105. (Be sure to leave at least one empty line
in the table below your view, because you are going to put another view there in the
next chapter.)
Figure 4-31 Pasting a view in a table
Tip: To preserve the original header labels in the view, go to the newly pasted view, and
select and delete each column, one-by-one. Select all columns in the Current Reports view
and Copy and Paste them into the newly created view.
104
IBM Workplace 2.5 Development with Workplace Designer
Figure 4-32 Re-pasted view columns
5. After the view columns are ready (Figure 4-32), you can merge the selection conditions in
your view with those in the Archives view, so that the new view displays documents with
Current and Archived statuses:
a. Click the entire view, go to the Properties pane. and click the Data tab.
b. Click the Edit button located below and to the right of the Static JavaScript conditions
check box. The Script Editor opens.
c. Enter the script shown in Figure 4-30 in the Script Editor, which is a combination of the
selection formulas in the Current and Archived views.
Example 4-30 Manager view’s selection formula
(document.getStringValue("statusReport/status") = "2") ||
(document.getStringValue("statusReport/status") = "3")
Tip: You can write the code shown in Example 4-30 using @Functions:
(@GetTextField("status") == "2") || (@GetTextField("status") == "3")
d. Click OK.
6. The search conditions are now merged. You can sort this view first by user names and
then by their date fields; however, before you do this, you need to move the Person name
column to the very first position instead of the check box column as follows:
a. Right-click the check box column and choose Delete. (You do not need the column for
managers, because they are not allowed to delete documents.)
a. Right-click the Person name column and choose Cut.
b. Right-click the (Hidden Date) column and choose Paste. (This moves the Person name
column to the very first position). Your view in the Workplace Designer should look like
that in Figure 4-33 on page 106.
Chapter 4. Developing the sample application: Intermediate development topics
105
Figure 4-33 Status reports by users
7. To set up sorting properties for the view, follow these steps:
a. Go to the Properties pane and click Sort/Filter. From Sort first by this column, select
the first available item below None (this is the column located to the very left in the
view). Change it to Ascending.
b. From Then sort by this column, choose the second available item below None (this is
the second column from the left in the view). Change it to Descending as shown in
(Figure 4-34).
Figure 4-34 Sort a view by two columns
8. Click the Basic tab in the Properties pane and change the name of the view control to
StatusReportsByUsers.
Hiding views depending on user roles
To hide the manager’s view:
1. Click the first table in the form (it contains the newly created view for managers).
2. Click the small arrow in the title bar of the Properties pane and choose Form as shown in
Figure 4-35 on page 107.
106
IBM Workplace 2.5 Development with Workplace Designer
Figure 4-35 Table properties
3. Position your cursor on the Visible field and click the small {n} symbol that appears.
4. Choose Computed from the menu.
5. Enter the code shown in Example 4-31 in the JavaScript editor, then click OK.
Example 4-31 Manager view Visible formula
import UtilityScripts;
return hasRole("Administrator");
To hide the Draft, Current, and Archived views:
1. Click the second table in the form.
2. Click the small arrow in the title bar of the Properties pane and choose Form.
3. Position your cursor on the Visible field and click the small {n} symbol that appears.
4. Choose Computed from the menu.
5. Enter the code shown in Example 4-32 in the JavaScript editor, then click OK.
Example 4-32 Users view Visible formula
import UtilityScripts;
return !hasRole("Administrator");
loo
Note: The Visible formulas in Example 4-31 and Example 4-32 look very similar. The
difference between them is the exclamation point (!) before the hasRole(...) function.
Testing your form (optional)
To test your form, follow this procedure:
1. Save your form by selecting File → Save.
2. Click anywhere on your component in the Component Navigator.
3. In the main menu, click File → Component → Deploy... and in the Deployment
Component dialog (Figure 4-36 on page 108), click OK.
Chapter 4. Developing the sample application: Intermediate development topics
107
Figure 4-36 Deploy Component
4. Open your Web browser and log in as manager. Your portlet should resemble the one
shown in Figure 4-37.
Figure 4-37 AllStatusReports form (manager version)
Simplifying debugging (optional)
This process is very similar to that described in “Simplifying debugging (optional)” on
page 101. You add fields and buttons that can help you test your component as follows:
1. Open the StatusReportEdit form.
2. Add two additional rows to the debug table that you previously created.
3. In the first new row, add the label Current roles and create a computed field that uses the
code in Example 4-33.
Example 4-33 JavaScript for returning the user roles.
context.getUser().getRoles();
4. In the next row, create two buttons, Grant Administrator Role and Remove Administrator
Role.
5. For the Grant onClick, use the code in Example 4-34.
Example 4-34 onClick code for Grant Administrator Role
context.getUser().addRole("Administrator");
6. For the Remove onClick, use the code in Example 4-35.
Example 4-35 onClick code for Remove Administrator Role
context.getUser().removeRole("Administrator");
7. Save and close the form.
108
IBM Workplace 2.5 Development with Workplace Designer
4.7 Deploying and testing
The application enhancements for this chapter are now complete. It is now time to test the
component, if you have not been doing this incrementally, to make sure that everything works.
Note: We do not describe a full deployment here; that topic is covered in Chapter 6,
“Templates” on page 145.
See 3.7.1, “Step-by-step: Deployment” on page 68, if you need instructions on a test
deployment. Some things to remember while you are testing include:
򐂰 You should be able to use any other user registered as the manager. Log in as one of
these users to see how the workflow is applied.
򐂰 To create categories, you must have the administrator role.
򐂰 To make use of the roles, you must use the debugging features we added to grant yourself
the administrator role, because this is not part of a template at this time.
Figure 4-38 on page 110, Figure 4-39 on page 111, and Figure 4-40 on page 111 illustrate
the application as it should appear at this point.
Chapter 4. Developing the sample application: Intermediate development topics
109
Figure 4-38 Sample status report
110
IBM Workplace 2.5 Development with Workplace Designer
Figure 4-39 Draft document
Figure 4-40 Document moved to Status
Chapter 4. Developing the sample application: Intermediate development topics
111
112
IBM Workplace 2.5 Development with Workplace Designer
5
Chapter 5.
Developing the sample
application: Advanced
development topics
This chapter provides deeper insight into the features of Workplace Designer. We expand
upon the application that you have developed using the previous chapters as a guide and
show you how to add additional features and functionality.
This chapter demonstrates the use of the following tasks:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Adding panels to forms
Using multiple nested panels
Defining component parameters
Adding advanced filtering to the views
Using the Workplace mail service to send mail messages
Creating component scripts
© Copyright IBM Corp. 2005. All rights reserved.
113
5.1 Working with panels
A Panel UI control covers a specified rectangular area of a form and can contain other UI
controls. Panels are very flexible. You can use them to group a collection of UI controls in a
form, or you can use them to contain the entire contents of the form. Also, panels can repeat
their contents for a specified number of times based on either static conditions in the XML
document or a JavaScript condition. You can set various properties for panels using the
Properties panel located at the bottom of the window. You can customize the format of panels,
associate panels with schema fields so that user input is stored properly, and more. By
default, panels inherit the schemas and documents that are associated with the panel form.
5.1.1 Step-by-step: Creating a panel
In this section, we demonstrate how to use the panel feature to add an expense table to the
StatusReportEdit form. This UI control displays all expenses that are related to a status
report. Using a button, the status report author can create a new expense entry, which
consists of an expense category, an item name, and the amount of the expense. The XPath
language is used to dynamically repeat the panel for each expense entry.
The activities for adding the expense feature to your application are:
򐂰 Modifying the statusReport schema to store the expense category, an expense item
name, the amount of the expense, and a total field
򐂰 Creating a panel in the StatusReportEdit form that displays the expenses
򐂰 Adding events to the StatusReportEdit form to manipulate the expense elements of the
panel
Modifying the statusReport schema
In this section, you learn how to create four new elements for the statusReport schema. Three
of the elements, expCategory, expItem, and expAmount, build an entry in the expense panel.
The panel repeats its content for each expense entry. Because you want to refer to these
elements in the context of their own data panels, you add a new complex data type called
expenses to the schema.
Tip: The possibilities for extending XML in schemas are vast and extensively documented
on the Web. For detailed documentation on XML and XML schemas, refer to the World
Wide Web Consortium Web site:
http://www.w3c.org
Follow these steps to modify the schema:
1. Open the statusReport schema.
2. Highlight the statusReport root element. Add a new child element called expenseSum. For
Field type, assign Double. This field stores the total amount of the expenses.
3. Highlight the statusReport root element again and add a new child element called
expenses. This serves as the root element for your panel.
4. Highlight the expenses element and add the following child elements:
a. expCategory (string)
b. expItem (string)
c. expAmount (double)
Your statusReport schema should now look like that shown in Figure 5-1 on page 115.
114
IBM Workplace 2.5 Development with Workplace Designer
5. Save and close the schema.
Figure 5-1 statusReport schema with expense elements
Adding a panel
Follow these steps to add the expense panel to the StatusReportEdit form:
1. Open the StatusReportEdit form.
2. Include the panel UI element in a table with one column and two rows as described in the
previous chapters. Add the new table below the Task View table on the form. To display a
title of this section, add a computed field with the Expenses string value to the first row.
Customize the border and background format in the same way as the first two tables.
3. One expense entry consists of three elements: an expense category, an expense item,
and an expense amount. To label these fields, you add a table with three columns to the
second cell and put the Category, Item, and Amount label UI controls in the columns. From
the Basics tab, set the width of the table to 100 percent. To access this option, click the
down arrow to the far right of the Properties panel for the table and choose Table.
Figure 5-2 shows how the tables look so far.
Figure 5-2 Expense table with a table of labels
4. Add a panel from the Container Controls palette beneath the label table and set the width
of the panel to 100 percent.
5. From the Data tab of the Properties pane for the panels, select Specify a data source for
this panel and enter the following values:
a. Type document_panel_1 as the name of the data source, if it was not entered
automatically. The Data source is the document where data entered in this form is
stored. The name that you specify can be used in scripts to reference the document.
b. Choose the statusReport schema to associate it with the panel.
Chapter 5. Developing the sample application: Advanced development topics
115
c. type expenses as the Data context. This is the root element of the schema associated
with the current document. Controls in the panel can be bound to this element or
elements below it, but not to elements above it in the schema hierarchy.
6. From the Document action, select Open document. Because this panel refers to the
current document, add the code from Example 5-1 to the Document ID field. This script
specifies the ID of the document to be opened by this form.
Example 5-1 JavaScript code of the expense panels open Document action
document.getId();
The Data tab of the panel should now look like that in Figure 5-3.
Figure 5-3 Data tab of the expense panel
7. To add logic that repeats the panel content for each expense entry of the status report,
click the Repeating tab of the Properties pane, and choose By XPath. Type in the XPath
expression from Example 5-2, which points to the expenses element in the XML document
to indicate the number of times to repeat the contents of the panel. Alternatively, you can
enter this expression using the XPath Editor.
Example 5-2 XPath expression for the expense panel
/statusReport/expenses
Your Repeating tab of the Properties pane for the panel should now look like that in
Figure 5-4 on page 117.
116
IBM Workplace 2.5 Development with Workplace Designer
Figure 5-4 Repeating tab of the expense panel
8. To add the expense UI controls to the panel, create a one-row table with three columns in
the panel. Match the table cell sizes of the new table to the table of labels above as shown
in Figure 5-7 on page 119.
9. Add a combo box to the first column. In the Values tab, choose From table and add
expense categories such as Business trip, Training, or Consulting to the table. On the Data
tab, bind this UI control to the expCategory element. Notice, in Figure 5-5, that only
statusReport schema fields, which are child elements of the expenses element, are
available. This is because you entered expenses as the root element in the Data context in
step 5, part c on page 116.
Figure 5-5 Panels combo box only shows the schema elements of the expenses root element
Note: If you have problems adding combo box values to the expCategory table in the panel
(for example, values disappear from the Value section), copy the UI control directly in the
form somewhere outside the panel. Then, change Data binding to another element (for
example, /expenses/expCategory) and add the category values to the Values tab. Cut and
paste the combo box back to the expense panel and rebind this UI control to the
expCategory element.
10.Add edit box controls to the second and third column. Bind them to the expItem and
expAmount elements. Assign Decimal Number to Display type for the expAmount edit
box.
11.To add a computed total field that sums and displays the expAmount values, create a third
table under the panel and add a computed field to a cell that is positioned below the
expAmount edit box. Add the JavaScript expression from Example 5-3 on page 118 to the
Value tab for the field. Refer to Figure 5-7 on page 119 to see how the table looks.
Chapter 5. Developing the sample application: Advanced development topics
117
Example 5-3 JavaScript to sum the expAmount values
var sumExpAmount = @Sum(document.getDoubleValues("/statusReport/expenses/expAmount"));
sumExpAmount.toFixed(2).valueOf();
Tip: To hide the space between the separate tables, position your cursor between the
tables and set the Visible option of the Paragraph Properties panel to False. To display this
option, click the down arrow to the far right of the Properties panel and choose Paragraph.
For details see Figure 3-16 on page 42.
12.Change the Alignment of the expAmount edit box and the computed sum field to Right as
shown in Figure 5-6. You find this option on the Format tab of the Properties panel for the
control.
Figure 5-6 Alignment of field values
13.Add a button at the bottom of the Expense table and label it Add Expense. Put the code in
Example 5-4 in the onClick event for the button. Make sure to choose Run on server. This
expression creates an empty expenses DOMElement and adds it to the current XML
document. The button enables the editor of a Status Report to enter the expense category,
item, and amount.
Example 5-4 JavaScript code for the Add Expense button
var expenses = new DOMElement("expenses");
document.getRootElement().addContent(expenses);
Because this button should only show in edit mode, add the code from Example 5-5 to the
computed property of the Visible field in the Basics tab.
Example 5-5 JavaScript for Add Expense visible property
document.isEditable();
14.Save the StatusReportEdit form. Your Expense table should now look like in Figure 5-7 on
page 119.
118
IBM Workplace 2.5 Development with Workplace Designer
Figure 5-7 Expense table
Adding code to the StatusReportEdit form events
At this point, you cannot add an expense entry for a new document unless you click the Add
Expense button, nor can you store the total of the expAmount elements in a separate field
(expenseSum). To accomplish these tasks, take the following steps:
1. Add the code in Example 5-4 on page 118 to the onPostNewDocument event for the form
to display an empty expense line for a new status report document.
2. Add the code in Example 5-6 to the onQuerySaveDocument event for the form.
Example 5-6 JavaScript code for the onQuerySaveDocument event
var sumExpAmount = @Sum(document.getDoubleValues("/statusReport/expenses/expAmount"));
document.setDoubleValue("/statusReport/expenseSum",parseFloat(sumExpAmount.toFixed(2).value
Of()));
3. Copy the code from Example 5-6 into the Save & Submit button so that it precedes
document.save().
4. Save and close the StatusReportEdit form.
You have now completed the design of your expense table. You can test this new feature by
adding the component (portlet) to your My Work page in the Workplace Collaboration
Services environment. Refer to 4.7, “Deploying and testing” on page 109 for illustrations of
deploying a component.
5.2 Sub-paneling
In this section, you learn how to add a comment table to your Status Report form so that the
author and the author’s manager can communicate with each other based on a status report
that has a current status.
5.2.1 Step-by-step: Creating a comment section using multiple panels
From a technical point of view, you combine several Workplace Designer technologies to build
the comment feature. They have already been introduced in previous chapters, but for the
comment section, you now interface them. First, you create a schema and a form for the
comment, which is a response document for a status report. To display the comment
response documents in the status report, you use a panel Container Control within a panel.
The first panel repeats for each comment, while the second panel, which is put inside the first
panel, opens the comment document and displays field values.
Chapter 5. Developing the sample application: Advanced development topics
119
Creating the comment schema
To create a schema for the comment documents, take the following steps, which give you
detailed information about how the schema has to be defined (for more information about how
to create a schema refer to 3.2, “Creating a schema” on page 32):
1. Create a new schema and name it comment.
2. Add the child elements in Table 5-1 to the schema.
Table 5-1 Elements of the comment schema
Element name
Field Type
comment
string
author
string
authorEmail
string
date
date
Figure 5-8 shows the comment schema in the Visual Editor.
Figure 5-8 Comment schema
3. Save and close the comment schema.
Creating the comment form
To create the comment form, which contains a Rich Text field for entering the comment:
1. Create a new form named CommentEdit and bind it to the comment schema.
2. Add a Add Comment label control to the top of the form.
3. Put a Rich Text UI control beneath the label and bind the field to the comment element.
4. Add the code in Example 5-7 to the Navigation Scripts library.
Example 5-7 Function for the Navigation Scripts library
function saveDocumentOpenParentRead(document, context, destination) {
if (document.isEditable()) document.save();
openParentDocument(document,context,destination,"false");
}
5. By clicking the author’s name for a comment, the user of a status report is automatically
forwarded to the assigned e-mail program for the browser. Example 5-8 on page 121
creates a mailto string based on a user’s distinguished name. In a following section, you
learn how to use this string to create a URL link in the StatusReportEdit form. Add this
function to the Utility Scripts library.
120
IBM Workplace 2.5 Development with Workplace Designer
Example 5-8 Utility Scripts function creates a mailto string
function getAuthorEmail(context:XSPContext, author:string) {
if (author == null || author.equals(""))
return "mailto:unknown@us.ibm.com";
return "mailto:" + context.getDirectory().getDirectoryUserMail(author);
}
6. To the button for the form, add an OK button that executes the code in Example 5-9 if an
onClick event occurs. This expression creates date and author fields for the comment,
saves the document, and brings the user back to the status report form.
Example 5-9 JavaScript code for the OK button
import UtilityScripts;
import NavigationScripts;
var author = getAuthorEmail(context, session.getDistinguishedUserName());
document.setStringValue("/comment/author",session.getCommonUserName());
document.setStringValue("/comment/authorEmail",author);
document.setDateValue("/comment/date",new Date());
saveDocumentOpenParentRead(document, context, "StatusReportEdit.xsp");
7. Add a Cancel button next to the OK button and add the code in Example 5-10 to the
onClick event.
Example 5-10 JavaScript code for Cancel button
import NavigationScripts;
openParentDocument(document, context, "StatusReportEdit.xsp","false");
Your CommentEdit form should now look like that in Figure 5-9.
Figure 5-9 CommentEdit form
8. Save and close the CommentEdit form.
Creating the comment table in the StatusReportEdit form
In this section, you learn how to add a fourth table to the StatusReportEdit form that serves as
the frame for the comments. Follow these steps to fulfill the necessary tasks:
1. Open the StatusReportEdit form.
2. Place a two-row and one-column table below the Expenses table and use the same
Format options that you assigned to the other tables in the StatusReportEdit form.
Chapter 5. Developing the sample application: Advanced development topics
121
3. In the first cell of this table, a hyperlink that a user can click to create a new comment is
needed. To create this, add a link UI control to this row and label it Add a comment.
4. Click the Basics tab of the link control and choose URL. You find this Link type in the
Options section on the right side of the panel. Add the code in Example 5-11 to the URL
field. The JavaScript expression returns a URL that creates a new comment as a response
document for the current status report.
Example 5-11 URL to create a new comment as response document
var url = context.getUrl();
url.setParameter("cameFrom", url.getAddress());
url.setAddress("CommentEdit.xsp");
url.removeParameter("id");
url.setParameter("parentid", document.getId());
url.setParameter("action", "newDocument");
url.setParameter("autoedit", "true");
url.setParameter("schema", "comment");
return url.toString();
Figure 5-10 Options section of the link control Basics tab
5. Because users should only be allowed to create comments for current status reports, add
the code in Example 5-12 to the Visible property of the link control.
Example 5-12 JavaScript code for the Visible property of the link
document.getStringValue("/statusReport/status") == "2";
6. For the title, add a computed field with the string value Comments to the first row. Add the
code in Example 5-13 to the Visible property to display the title for archived status reports
only.
Example 5-13 Visible property of the comment title
document.getStringValue("/statusReport/status") == "3";
7. Add a panel to the second row of the comment table, and set the height of the panel to
auto and the width to 100 Percent. Your comment table should look like that shown in
Figure 5-11 on page 123.
122
IBM Workplace 2.5 Development with Workplace Designer
Figure 5-11 The comment table in the StatusReportEdit form
8. From the Data tab, select Specify a data source for this panel and assign the
statusReport schema. Choose open Document action to add the code in Example 5-14
to the Document ID field, which refers to the current status report document.
Example 5-14 Document ID code to open the current document
document.getId();
9. Add the code in Example 5-15 to the By formula field of the Repeating tab for the panel.
The number of comment response documents dictates the number of repetitions of the
panel content.
Example 5-15 JavaScript code for the outer panel repeating code
document.getResponseCount(true);
10.Add a second panel inside the panel that you created in step 7 on page 122. This panel is
intended to display the comment document data such as comment, author, or date. Set
the panel height to auto and the panel width to 100 Percent.
11.From the Data tab for this interior panel, select Specify a data source for this panel and
choose the comment schema, which is also the root element for this panel. For Data
source, type document_panel_3, if it was not done automatically. The data source is the
document where data entered in this form is stored. You use this name in scripts to
reference the document.
Note: If you copy and paste a panel to another place on your form, the assigned Data
source might be cleared. Be sure to reassign the Data source values for this panel after
copying it.
12.Add the code in Example 5-16 to the Document ID field for the open Document action.
This code enables this panel to access the current comment response document. To
receive the current response document IDs, we used the getResponseDocumentIds()
method, which returns a list of response IDs that correspond to a status report. To access
a comment document, we used the getLoopIndex() method, which obtains the repetition
index of a repeating panel, starting at 0.
Example 5-16 JavaScript for the interior panels Document ID field
document.getResponseDocumentIds()[context.getLoopIndex()];
Chapter 5. Developing the sample application: Advanced development topics
123
Note: Because tasks are also response documents for a status report, the returned list for
getResponseDocumentIds() has task response IDs, too. Using a Visible property for specific
fields, you can filter the content of the panels (as demonstrated in the next steps) to show
comment response documents only.
13.From the Repeating tab for this panel, choose Never. This is because you want to display
the fields in this panel only once for each comment document.
To add UI controls to this panel to display the actual comment, the author name, the author
e-mail, and the creation date of the comment, follow these steps:
1. To access the current comment document, use the document_panel_3 data source, which
you assigned in the Data tab for the panel as follows:
a. Add a computed field with the code in Example 5-17 to this panel and set the height to
auto and the width to 100 Percent.
b. Select Treat computed value as markup text from the Basics tab for the computed
field. This enables the field to display the content of the comment as Rich Text.
Example 5-17 JavaScript expression displays the comment
document_panel_3.getStringValue("/comment/comment");
2. Because you only want to display the data for comment documents, add the code in
Example 5-18 to the Visible property of this computed field. If you do not set this property,
the control displays an empty line for each of the other response documents for the status
report (for example, Tasks).
Example 5-18 Visible property of the computed field
document_panel_3.getStringValue("/comment/comment")!="";
3. To display the information for the author of the comment:
a. Add a computed field, with an auto height and width setting beneath the comment UI
control. Type Comment created by as the string Value and set the Visible property as
shown in Example 5-18.
b. Put a blank next to this computed field and add a link UI control to display the name of
the author. In the label field of the Basics tab, enter the code in Example 5-19 and
assign the code in Example 5-20 to the URL code of this link. Set the Visible property
for this field using the code in Example 5-18. If a user clicks on the name of the author
of the comment, the mailto URL opens a new mail based on the assigned e-mail
program for the browser.
Example 5-19 Label displays the name of the author of the comment
document_panel_3.getStringValue("/comment/author");
Example 5-20 JavaScript code creates a mailto URL link
document_panel_3.getStringValue("/comment/authorEmail");
c. Put a blank after this field and add a computed field next to it. Enter the code in
Example 5-21 on page 125 to the Value tab and set the Visible property using the
code in Example 5-18.
124
IBM Workplace 2.5 Development with Workplace Designer
Example 5-21 Computed field displays the comments creation date
"on "+document_panel_3.getDateValue("/comment/date").toString();
d. After another blank, add the last computed field to this line and select Treat computed
value as markup text. The code shown in Example 5-22 creates an HTML tag to
display a separator and a carriage return below each comment. Remember to set the
Visible property using the code in Example 5-18 on page 124.
Example 5-22 Markup text creates a separator and a carriage return
"<br/><hr/>";
Note: To hide unused space in the tables or panels, position your cursor in the specific
area and set the Visible option of the Paragraph Properties panel to False. To display this
option, click the down arrow to the far right of the Properties panel and choose Paragraph.
For details, see Figure 3-16 on page 42.
Now, the comment table is complete. Figure 5-12 shows the panels with the frames in
different colors to distinguish the different functions. The red outer panel repeats as often as
the number of status report response documents. The blue interior panel refers to a comment
document, groups the associated controls, and displays the comment, author name, e-mail,
and creation date.
Figure 5-12 Comment table with two panels
4. Save and close the StatusReportEdit form.
In a browser, the Comments table looks like that shown in Figure 5-13.
Figure 5-13 Sample comments for a status report
Note: Because our StatusReportEdit form became quite long, we duplicated the buttons
from the top of the form at the bottom so that it is not necessary to return to the very top of
the form to use them.
Chapter 5. Developing the sample application: Advanced development topics
125
5.3 Parameters
When creating a Workplace component in Workplace Designer, users can define a set of
properties that can be configured as points of variability or parameters when an instance of
the component (portlet) is created. When the instance is created using the Workplace
Application Template Editor, the person instantiating the component can set the values of the
parameters that were designated by the Workplace Designer user. In other words,
parameters specify the property values of the application and the components (portlets) that
are deployed on each page of the application during run time.
The default value of a parameter can be provided by the application or a component, or it can
use the value of another parameter of the same data type. If the source of the default value is
the application or component, the parameter value is characterized as Self-defined. If the
source of the default value is another parameter of the same data type, the parameter value is
qualified by the name of the source parameter and its owner application or component.
Workplace Designer allows you to define parameters for components. Furthermore, you can
access these parameters directly from your JavaScript code during run time. In our
application, we used parameters to make the following properties of our application
customizable:
򐂰 Retrieve a title and use it on the StatusReportEdit form.
򐂰 Use application-wide categories for the expenses.
Tip: For more information, see the IBM Workplace Collaboration Services Information
Center on the Web at:
http://www.lotus.com/ldd/notesua.nsf/find/workplace
5.3.1 Step-by-step: Adding parameters to the component
Integrating parameters to your application basically consists of three steps:
򐂰 Define the parameters to be accessed during run time and add them to the component.
򐂰 Add code to the component to retrieve the parameter values from the deployed
application.
򐂰 Use Workplace Application Template Editor to customize values of the parameters in the
application template that contains the status report component (portlet).
Note: Parameter values are accessible during the run time of an application that is based
on a template. If you add the component (portlet) only to a page, like we did in the previous
deployment chapters, there is no access to the parameters. To test the parameter logic that
we introduce in this section, you must add your component (portlet) to an application
template using the Application Template Editor. Refer to Chapter 6, “Templates” on
page 145 for detailed information about this topic.
Defining parameters
To add a formTitle parameter and an expenseCategories parameter to your component, these
parameters must first be defined. Follow these steps to fulfill this task:
1. Click the Status Report component in the Component Navigator.
2. Click the Parameters tab in the Properties panel. From this tab you can add, edit, and
delete parameters for this component.
3. Click New.
126
IBM Workplace 2.5 Development with Workplace Designer
4. Enter these values in the Define Parameter dialog (Figure 5-14):
a. Type formTitle for the name for the parameter.
b. Type Enter a title (i.e. Status Report) for the user prompt.
c. Choose Text as the Type for this parameter.
d. Choose Edit Box as Entry format and leave Default value blank.
Figure 5-14 Define a new parameter
Note: If you enter a Default value combined with an Edit Box parameter you might not be
able to change the value of this parameter in your application template. This value is
hard-wired to the parameter. Using the Combo Box Entry format, you can define a list of
values and set one value as a Default value.
5. Repeat steps 1 to 4 to create an expenseCategories parameter for your component. Type
Please enter the expense categories (separate them with a comma) for User prompt.
This comma-separated parameter is used later to offer a combo box from which users can
choose an expense category.
Your parameter panel should now look like that in Figure 5-15.
Figure 5-15 Parameters tab for the Properties panel for the component
Chapter 5. Developing the sample application: Advanced development topics
127
Using a parameter to display a title
You can now add code to the component that obtains the value of the formTitle parameter
during run time and displays it in a status report document. Add code to a script library and
modify the StatusReportEdit form to show the value of the formTitle parameter as follows:
1. Add the function from Example 5-23 to the Utility Scripts library to retrieve the value of a
given application parameter. Access the component parameters by using the
getComponentParameter method for the XSPContext class, which represents the context of
the document server execution.
Example 5-23 JavaScript code to obtain an application parameter value
function getAppParameter(param:String) {
var appParamDefault = "";
var appParam = context.getComponentParameter(param);
if( appParam=="" ) {
appParam = appParamDefault;
}
return ( appParam );
}
2. Open the StatusReportEdit form. Add a computed field to the first row of the first table. Be
sure that the label field is blank.
3. Add the code in Example 5-24 to the Value tab for the computed field. This computed field
displays <untitled> in a browser if you only deploy the component (portlet) directly to the
page without using a template or if the formTitle parameter of the application template is
empty. Figure 5-16 shows how the table should look.
Example 5-24 JavaScript for the computed field
import UtilityScripts;
dbName = getAppParameter("formTitle");
if (dbName == "") {
"<untitled>";
} else {
dbName;
}
Figure 5-16 Computed field retrieves the value from the formTitle parameter
128
IBM Workplace 2.5 Development with Workplace Designer
After the component (portlet) is added to a template, the application owner can enter a title
using the formTitle parameter so that when a user accesses the application, the title is
displayed in the status report document. Figure 5-17 shows a document in a browser with the
Status Report title.
Figure 5-17 A computed field displays the value of the formTitle parameter
Please refer to Chapter 6, “Templates” on page 145 to obtain detailed instructions for creating
an application template and modifying parameter values.
Using a parameter to build an expense category list
Now it is time to enhance the Expense Categories combo box, which is bound to the
/expenses/expCategory element, to support a more dynamic way of retrieving categories.
The new combo box offers a list of categories from the expenseCategories parameter. Follow
these steps to add a new function to the UtilityScripts library and add code to the
expCategory combo box:
1. Add the code in Example 5-25 to the Utility Scripts library. This function creates a string
array from a comma-separated parameter value.
Example 5-25 JavaScript code to get a string array from a parameter
function getAppParameterList(param:String) {
var paramList;
var paramArray = new Array();
if (context.getComponentParameter(param) != "") {
paramList = context.getComponentParameter(param);
var indexOfComma = paramList.indexOf(",");
var arrIndex = 0;
while (indexOfComma != -1) {
paramArray[arrIndex] = paramList.substring(0, indexOfComma);
paramList = paramList.substring(indexOfComma + 1);
arrIndex++;
indexOfComma = paramList.indexOf(",");
Chapter 5. Developing the sample application: Advanced development topics
129
}
paramArray[arrIndex] = paramList;
}
return paramArray;
}
Tip: You can easily navigate through your Utility Scripts functions by using the Outline tab
of the JavaScript Editor. Figure 5-18 shows some of the functions that we have already
added to the UtilityScripts library.
Figure 5-18 Outline displays functions of UtilityScripts library
2. Open the StatusReportEdit form. Click the Value tab of the expCategory combo box and
change create Selection to from formula.
3. Use the JavaScript Editor to add the code in Example 5-26 to this combo box.
Example 5-26 JavaScript for the expenseCategory combo box
import UtilityScripts;
getAppParameterList("expenseCategories");
4. Save and close the StatusReportEdit form.
Note: If you experience problems adding code to the expCategory combo box in the panel
(for example, the code in the Value section disappears), copy the combo box directly in the
form somewhere outside the panel. Then change Data binding to another element (for
example, /expenses/expCategory) and add the code in Example 5-26 to the Value section
of the combo box. Cut and paste the combo box back to the expense panel and rebind this
UI control to the expCategory element.
For the Status Report application shown in Figure 5-19 on page 131, the application owner
assigned Business trip, Training, and Consulting (comma-separated values) to the
expenseCategories parameter. The combo box displays the expense categories, based on
the parameter values for the template.
130
IBM Workplace 2.5 Development with Workplace Designer
Figure 5-19 Combo box displays values from the expenseCategories parameter
5.4 Advanced filtering
This section shows you the last and most advanced view filtering technique. The basic
difference between this method and the methods you have used so far is that this one lets you
define queries in views at run time. There are a few cases when runtime queries are essential
and there is no other alternative method to use instead of them:
򐂰 The queries depend on the current system date.
If you want to display documents created a certain number of days ago or a specific
number of months old, you must use a runtime query because it must contain the current
system date (and thus cannot be compiled at the time of deployment).
򐂰 The queries depend on input from the user.
Whenever you want to filter a view based on some information that a user provides at run
time, you cannot use any other query than the one constructed at run time.
In this section, we provide examples of both cases.
5.4.1 Step-by-step: Filtering documents that are not older than one week
Our intention is to point out those status reports that do not have a current version from the
last week (the last 7 days). To do this, we created a new view in the manager’s section that
displays documents that:
򐂰 Are in current status
򐂰 Contain dates older than one week (date < today - 7 days)
We used the AllStatusReports view for this demonstration. Figure 5-20 on page 132
illustrates our plans.
Chapter 5. Developing the sample application: Advanced development topics
131
Figure 5-20 OldStatusReportsView
To create this filter, follow this process:
1. Create a new view based on an existing view:
a. Open the AllStatusReports form. Select the entire first view on the form, right-click it,
and choose Copy.
b. Right-click somewhere below this view, but inside the same table (so that this view is
hidden for users who are not managers, together with the whole table). Choose Paste.
Tip: To copy the view header labels from the original view to the new one quickly, select all
columns in the new view, delete them one-by-one, and paste them from the original view.
2. Create a label for the new view:
a. Drag a new Label control from the UI Controls pane above your new view on the form.
b. In the Properties pane, change the text to Status reports not updated in one week
and set the font style to Bold.
3. Apply a dynamic filter in the view:
a. To simplify date operations to number operations, you can change the data type of the
(Hidden Date) column from date to number. To do this, click the body of the column, go
132
IBM Workplace 2.5 Development with Workplace Designer
to the Data tab in the Properties pane, change the data binding for the column to
Formula, and enter the code in Example 5-27 in the Script Editor.
Example 5-27 Converting a date to a number
document.getDateValue("statusReport/date").getTime()
Tip: You can write the code shown in Example 5-27 using @Functions:
@GetDateField("date").getTime()
b. Click the (Hidden Date) column in the new view and remember its name (for example,
column_2).
c. Select the entire new view and in the Properties pane, click Sort/Filter.
d. From the Filter options, select Show items meeting the following dynamic
conditions (Figure 5-21).
Figure 5-21 Applying a dynamic filter
e. Click the Edit button and enter the code in Example 5-28 in the Script Editor. Replace
column_2 with the name of your (Hidden Date) column in this view.
Example 5-28 Filter formula for status reports not updated in one week
// Create a date object (it is automatically initialized to the current system date)
var last_week = new Date();
// Subtract 7 days from the current day of month
last_week.setDate(last_week.getDate() - 7);
// Construct the filter formula
"column_2 < " + last_week.getTime()
Note: Filter conditions for views are query strings written in the Workplace Designer
internal query language. The script editor in this case helps construct such a query using
JavaScript.
Tip: You can write the code shown in Example 5-28 using @Functions:
"column_2 < " + @Adjust(@Today(), 0, 0, -7, 0, 0, 0).getTime()
Chapter 5. Developing the sample application: Advanced development topics
133
Note: In practice, after you deploy your component with the dynamic filter, instead of your
view, you might get a Workplace Designer Runtime Exception that says that there is a
DATE and BIGINT type mismatch. This can happen if the (Hidden Date) column in your
view was corrupted while you were changing the data type.
In this case, simply delete the column and create it again with the correct computed
formula.
5.4.2 Step-by-step: Displaying document from a date range defined by user
Our goal in this section is to show you how to filter views that depend on some type of data
that a user enters in a form. When you use our example, you create your own search pages
where you can ask users to enter their own criteria and filter your view based on that criteria.
You also learn how to modify the status reports for the member view that you already have for
the form by adding two new text fields to the form to collect information from the user and a
search button that refreshes the view when the user clicks it.
In addition, we show you how to use the sessionData object to store the date range
persistently after it is entered by the user until the end of the session or until a user changes it
again. Figure 5-22 illustrates the plan.
Figure 5-22 Dynamic filtering
To provide dynamic filtering, follow this process:
1. Create a new schema that contains data bindings for the From and To search fields as
follows:
a. Create a new schema in your component. To do this, right-click the component in the
Component Navigator and choose New → Schema.
b. Assign a name to your schema: search
c. Right-click the root element (search) and choose Append Element → As Child.
134
IBM Workplace 2.5 Development with Workplace Designer
d. Change the name of the new element to dateRange.
e. Right-click the dateRange element and choose Append Element → As Child.
f. Name the new element searchFrom and set its type to Date.
g. Right-click the dateRange element again and choose Append Element → As Child.
h. Name the new element searchTo and set its type to Date.
i. Verify that your schema corresponds with the illustration in Figure 5-23.
j. Save and close.
Figure 5-23 The final search schema
2. Now, you add the search fields to the AllStatusReports form. You can assign the correct
search schema to either parent element (a form or a panel), but because you do not want
to add a schema to the whole form, you put it into a panel as follows:
a. Select the Panel container control from the UI Controls pane and drag it to your form
below the Manager Task Categories button. Set the Basic properties according to
Table 5-2 and optionally verify that the panel resembles that in Figure 5-24.
Table 5-2 Search panel basic properties
Property
Value
Height
Auto
Width
100 Percent
Figure 5-24 Search panel
Chapter 5. Developing the sample application: Advanced development topics
135
b. Set the Data properties for the panel according to Table 5-3 and optionally verify that it
resembles that in Figure 5-25.
Table 5-3 Search panel data properties
Property
Value
Data source
document_panel_1
Schema
search
Data context
dateRange
Figure 5-25 Search panel data properties
c. In the UI Controls pane, click the Edit box and drag it twice to panel_1. Set the
properties of the first one so that they match Table 5-4.
Table 5-4 SearchFrom properties
Property
Value
Label
Search reports from:
Height
Auto
Width
Auto
Data source
document_panel_1 (not editable, only verify)
Schema
search (not editable, only verify)
Data binding
searchFrom
Default value
Computed, set as shown in Example 5-29
Display type
Date or time
Validation
Date/time Format
<date>
Note: allStatusReports_searchFrom (Example 5-29) is the name of a sessionData
member for storing information that a user has typed previously in this field. Use the
onClick event of a Search button to set the value of this property. For more information
about sessionData, see 4.2, “Optional: Dynamic combo boxes” on page 81,.
Example 5-29 SearchFrom default value
sessionData.allStatusReports_searchFrom
136
IBM Workplace 2.5 Development with Workplace Designer
d. Set the properties of the second edit box according to Table 5-5. The SearchTo default
value is shown in Example 5-30.
Table 5-5 SearchTo properties
Property
Value
Label
to:
Height
Auto
Width
Auto
Data source
document_panel_1 (not editable, only verify)
Schema
search (not editable, only verify)
Data binding
searchTo
Default value
Computed, set as shown in Example 5-30
Display type
Date or time
Validation
Date/time Format:
<date>
Example 5-30 SearchTo default value
sessionData.allStatusReports_searchTo
3. Add the last control to the panel, a search button. In the UI Controls pane, click the Button
control and put one in panel_1. Set its properties according Table 5-6.
Table 5-6 SearchFrom properties
Property
Value
Label
Search
Height
Auto
Width
Auto
Format style category
Portlet Form-Related Text
Format style
portlet-form-button
onClick event
See Example 5-31
Example 5-31 Search button’s onClick event
// Update session-data
sessionData.allStatusReports_searchFrom =
document_panel_1.getDateValue("/dateRange/searchFrom");
sessionData.allStatusReports_searchTo =
document_panel_1.getDateValue("/dateRange/searchTo");
// Refresh the page
u = context.getUrl();
u.removeParameter("subquery")
context.redirectUrlOnServer(u.toString())
4. Verify that your results resemble the image in Figure 5-26 on page 138.
Chapter 5. Developing the sample application: Advanced development topics
137
Figure 5-26 Search panel check-point
5. Now, you perform the most important step of this section: adding a user-defined filter to
the view called Status reports by users.
a. Click the (Hidden Date) column and remember the name (for example, column_5).
b. Highlight the complete view, go to the Properties pane, and click Sort/Filter.
c. Choose Show items meeting the following dynamic conditions (the window shown
on Figure 5-21 on page 133).
d. Click Edit and add the code shown in Example 5-32 to the script editor.
Example 5-32 Dynamic view filter
var from = sessionData.allStatusReports_searchFrom;
var to
= sessionData.allStatusReports_searchTo;
if ((from != null) && (to != null)) {
return "column_5 >= " + from.getTime() + " AND column_5 <= " + to.getTime()
}
Important: Be sure to replace every occurrence of column_5 in the code with the
appropriate column name from step 5a.
6. The last step in the process is to specify default values for the search From and To fields
that the users see when they first open the form. The edit fields use sessionData members
as their default values, so the only thing that you need to do is set these values when the
form is being loaded in case they are empty:
a. In the Properties pane, switch to Form properties by using the small arrow in the title
bar of the Properties pane.
b. From the Event tab, choose onPageLoad as shown in Figure 5-27 on page 139.
138
IBM Workplace 2.5 Development with Workplace Designer
Figure 5-27 The onPageLoad event for the form
c. Enter the code shown in Example 5-33 to the body of the event.
Example 5-33 AllStatusReports form’s onPageLoad event
var search_from = sessionData.allStatusReports_searchFrom;
var search_to = sessionData.allStatusReports_searchFrom;
if ((search_from == null) || (search_to == null)) {
// Default 'from' = one month ago
search_from = new Date();
search_from.setMonth(search_from.getMonth() - 1);
// Default 'to' = today
search_to = new Date();
sessionData.allStatusReports_searchFrom = search_from;
sessionData.allStatusReports_searchTo
= search_to;
}
Note: Optionally, in Example 5-33, you can change the search_from and search_to
variables to contain other dates.
Testing your view (optional)
If you now deploy your component by logging in as a user with an Administrator role, your
portlet should open with the two views shown in Figure 5-28 on page 140.
Chapter 5. Developing the sample application: Advanced development topics
139
Figure 5-28 User-defined dynamic filtering
5.5 Workplace Collaboration Services API
Workplace Designer has native support for the Workplace Collaboration Services API. This
allows you to create objects that interact with the Workplace Collaboration Services server
business components such as mail, calendar, and Web conferencing. For more information
about the Workplace Collaboration Services API visit:
http://www.lotus.com/ldd/lwpapi
To use a service, you must ensure that the specified service is running on the server. For
example, to use the mail service, you must ensure that Mail_Server_1 has been started.
In our application, we made use of the WorkplaceMail object. This object, along with the other
similar objects available in Workplace Designer, is a JavaScript wrapper object that exposes
the features of the corresponding Workplace Collaboration Services API services (in this
case, Mail). These objects provide a convenient entry point to the various services and their
associated data objects in the published Workplace Collaboration Services API. Hence, in our
application, when an author submits a document, or if a comment is created for a specific
report, then the author, the manager, or both are alerted automatically by e-mail.
When using the Workplace Mail API, you begin by creating a WorkplaceMail object and a mail
message. Then you populate the message with the elements such as sender, receiver,
subject, and body. After these tasks are complete, you can use the WorkplaceMail object to
send the e-mail.
Tip: You need to specify all the elements (to, sender, subject, and body) to have the
message send successfully. If you don’t need to use a piece, such as body, then set it to
the empty string ("").
Step-by-step: Adding Workplace Mail services
To add Workplace Mail services, follow these steps:
1. Change the Save & Submit button for StatusReportEdit to match the code in
Example 5-34 on page 141.
140
IBM Workplace 2.5 Development with Workplace Designer
Example 5-34 WorkplaceMail added to Save & Submit button
import NavigationScripts;
import UtilityScripts;
var mgrEmail = document.getStringValue("/statusReport/managerEmail");
var usrEmail = document.getStringValue("/statusReport/userEmail");
if (mgrEmail!="") {
var manager = document.getStringValue("/statusReport/manager");
readers = document.getReaders();
if (manager != "") {
readers.add("statusReportReaders",manager);
}
document.setStringValue("/statusReport/status","2");
var body = "A new report is awaiting your review.";
sendEmail(usrEmail,mgrEmail,"A new Status Report has been submitted",body);
pageData.hasSearchFailed = false;
saveCurrentDocumentEdit(document,context,"AllStatusReports.xsp");
} else {
pageData.hasSearchFailed = true;
};
2. Change the code for the OK button in the CommentEdit form to match Example 5-35.
Example 5-35 WorkplaceMail added to CommentsEdit Save button
import UtilityScripts;
import NavigationScripts;
var authorDN = session.getDistinguishedUserName();
var author = getAuthorEmail(context, authorDN);
document.setStringValue("/comment/author",session.getCommonUserName());
document.setStringValue("/comment/authorEmail",author);
document.setDateValue("/comment/date",new Date());
var parentManager = document.getParentDocument().getStringValue("/statusReport/manager");
if (authorDN.equalsIgnoreCase(parentManager))
var receiver = document.getParentDocument().getStringValue("/statusReport/userEmail");
else
var receiver =
document.getParentDocument().getStringValue("/statusReport/managerEmail");
sendEmail(author,receiver,"A new comment has been posted","Please see the Status Report for
more information");
saveDocumentOpenParentRead(document, context, "StatusReportEdit.xsp");
3. Add the code in Example 5-36 on page 142 to the Utility Scripts library.
Chapter 5. Developing the sample application: Advanced development topics
141
Example 5-36 sendEmail function to be added to UtilityScripts
function sendEmail(sender:String, reciever:String, subject:String, body:String){
var wpmail = new WorkplaceMail();
if (wpmail == null) {
print("WorkplaceMail not created for");
return;
}
wpmail.initialize();
var msg = wpmail.createMailMessage();
var msgopt = wpmail.createMailSendOptions();
msgopt.setDeliveryNotificationOption(msgopt.NOTIFICATION_FAILURE);
var toList = msg.getTo();
toList.add(reciever);
msg.setSender(sender);
msg.setSubject(subject);
msg.setBodyText(body);
wpmail.sendMessage(msg,msgopt);
}
5.6 Component scripts
Component scripts allow you to add business logic to the event life cycle of your Workplace
component. Workplace Application Template Editor defines a life cycle for components. When
you create an instance of a component, numerous events are being fired, such as create
instance, remove instance, and add members. You can use Workplace Designer to provide
script to add programmatic logic to those events that are going to be used by Workplace
Application Template Editor.
Note: To use a component script in Workplace Collaboration Services 2.5.1 you must
deploy an interim fix (iFix) first. This iFix is called LOD6N7T and enables JavaScript logic
for component parameters. You install this iFix using the IBM WebSphere Portal Update
Installer. More information about installing this iFix can be found at this Web site:
http://www-1.ibm.com/support/docview.wss?uid=swg24010240
5.6.1 Step-by-step: Creating a component script
In this section, we show you how to use a component script in your application to create a
sample document that status report authors can use as a guideline for creating their own
status reports. To add a component script to your application that creates a document, if a
new instance of this component (portlet) is created, follow this process:
1. Expand the Status Report component in the Component Navigator.
2. Expand Scripts and double-click Component Scripts.
3. Click createInstance and add the code in Example 5-37 on page 143.
142
IBM Workplace 2.5 Development with Workplace Designer
Example 5-37 Component script for the Status Report component
print ("Status Report Application: creating sample doc...");
var newDoc : DBDocument;
var currentDn = session.getDistinguishedUserName();
var statusReportOwner=new Array(currentDn);
newDoc = database.createNewDocument("statusReport");
newDoc.setForm("StatusReportEdit");
newDoc.setStringValue("/statusReport/activity", "Sample Activity");
newDoc.setStringValue("/statusReport/status", "1");
newDoc.setDateValue("/statusReport/date", new Date());
newDoc.setStringValue("/statusReport/summary", "<<< This document was created by using a
component script! Since it does not have document level security, you should use this as
a guideline, and keep it in draft mode. >>>");
newDoc.setStringValue("/statusReport/name",currentDn);
newDoc.setStringValue("/statusReport/commonUsername",session.getCommonUserName());
var expenses = new DOMElement("expenses");
newDoc.getRootElement().addContent(expenses);
newDoc.setStringValue("/statusReport/expenses/expCategory","Business trip");
newDoc.setStringValue("/statusReport/expenses/expItem","Taxi");
newDoc.setDoubleValue("/statusReport/expenses/expAmount",50);
newDoc.setDoubleValue("/statusReport/expenseSum",50);
newDoc.save(true);
print ("Status Report Application: sample doc created.");
Tip: The print() statement used in Example 5-37 can also be used to debug code. The
output of this statement is printed to the WebSphere Portal Server SystemOut.log file.
When the component (portlet) is instantiated, this script creates a new document based on
the statusReport schema and assigns it to the StatusReportEdit form. The status of the
sample Status Report is set to Draft and several fields are filled with sample data.
Figure 5-29 on page 144 shows the component script editor with the code from
Example 5-37.
Chapter 5. Developing the sample application: Advanced development topics
143
Figure 5-29 Component script editor
144
IBM Workplace 2.5 Development with Workplace Designer
6
Chapter 6.
Templates
You can take the component that you have built based on the instructions in the previous
chapters and deploy it into an actual template. Then, you can roll out multiple applications and
provide the full-featured set of a Workplace component.
In this chapter, we show you how to:
򐂰 Create a template.
򐂰 Set up the template with roles and parameters.
򐂰 Use the template in an application.
© Copyright IBM Corp. 2005. All rights reserved.
145
6.1 Overview
Templates are a collection of portlets in individual or multiple pages that can be turned into
applications. The power of templates is that you can create a specific layout of specific
portlets in certain pages that together can focus on meeting a targeted business purpose. You
could create an application by making a page from the Welcome page of Workplace
Collaboration Services, then adding portlets to it; however, in this process you would lose the
idea of roles, and each user would have to add all the portlets manually. Figure 6-1 shows
how a template fits into the flow of creating applications from components.
Figure 6-1 Component to application flowchart
To put your component into an application, you follow a process with three phases:
򐂰 Creating the template
򐂰 Setting up the template
򐂰 Deploying the template into an application
6.2 Creating templates
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.
6.2.1 Step-by-step: Creating a template for your component
To create a template for your component, follow these steps:
1. Deploy the component as described in 3.7.1, “Step-by-step: Deployment” on page 68.
2. Log in to the Workplace Collaboration Services environment as a user who has
permission to create templates.
3. Click the Templates button at the top of the window.
4. In the Application Template Library portlet, click the New... button.
5. Give the template a name that describes its purpose, such as Team Tracking.
6. Place it in the Team Space category.
146
IBM Workplace 2.5 Development with Workplace Designer
7. You can build your template from existing templates, or create a new blank one. For this
deployment, you build from the Team Project template (Figure 6-2).
8. Click OK.
Figure 6-2 Creating a template
After the application is created, the Workplace Application Template Editor opens
(Figure 6-3). At this point, you can edit the properties that you set when you created the
template and you can set up the method of template construction. You also have the option of
clicking Save and Close to use the default settings.
Figure 6-3 Template set up page in Workplace Designer
Chapter 6. Templates
147
6.3 Template setup
After you create a template, the next step is to modify the default settings in Workplace
Application Template Editor. By setting up the template, you can map the Workplace Designer
access levels to the template roles and set default settings for the component parameters.
6.3.1 Step-by-step: Creating pages
These are the steps for setting up your template:
1. From Workplace Application Template Editor, click the Pages and Layout menu.
2. Click New Page... to create a page for your status reporting component.
3. Label the new page Status Reports as shown in Figure 6-4. Use a one-column layout.
4. Click Add portlet and find the component you deployed to the server.
5. Click OK.
Figure 6-4 Adding our component to a new page
6. Click OK again.
7. On the Pages and Layout page, move the new form so that it becomes the third page by
clicking the “up” triangle (Figure 6-5 on page 149).
148
IBM Workplace 2.5 Development with Workplace Designer
Figure 6-5 Re-ordering the page
6.3.2 Step-by-step: Mapping roles
The security of a Workplace component is divided into document-level security and
role-based security. For this sample application, you do not modify any of the document-level
security in the Workplace Application Template Editor, but you must map the roles to exploit
the differentiated views and buttons. You do this as follows:
1. Click the Roles panel.
2. Your component only uses the two roles that you have already defined, so there is no need
to add any additional roles. However, you do modify the mappings of this template. Start
by clicking the Moderators link.
3. To make it more clear, rename the role to Team Leader.
4. Change the level of access for our component to Administrator as shown in Figure 6-6 on
page 150. You do not need to change the page access, so leave it as User.
Chapter 6. Templates
149
Figure 6-6 Modified moderator role
5. Click OK.
6. Open the Contributors role and rename the role to Team Member.
7. Leave all other settings at default, and click OK.
6.3.3 Step-by-step: Creating default parameters
Parameters specify the property values of the component that are deployed on each page of
the application at run time. In your application, you use the parameters to help define the form
title and the types of expenses that can be used. To create default parameters, follow these
steps:
1. Click Parameters in the left panel of Workplace Application Template Editor.
2. On the Parameters page (Figure 6-7 on page 151), you can modify any of the defaults
provided. Here, you change the defaults on the StatusReport component, so click Enter a
title (ie. Status Reports).
150
IBM Workplace 2.5 Development with Workplace Designer
Figure 6-7 Parameters Screen
3. Change User Prompt to Enter a title: and type Status Report for Default Value
(Figure 6-8).
Figure 6-8 Changing Parameter defaults
Chapter 6. Templates
151
4. Click OK to return to the Parameters page.
5. Change the default value of the second parameter to a list of values such as Business
Trip, Training, Consulting.
6. Click OK. Your Parameters page for the Status Report page should appear like that in
Figure 6-9.
Figure 6-9 Parameters for Status Report page
7. Click Preview if you want to see the template that you created. Click Save and Close
when you are satisfied with the new template. If you do preview the template, click Done
Previewing at the top of the page to return.
6.4 Using templates
If you have a list of users that you know want to implement this template, then you must make
sure that they have access to create applications based on the template. In this section, we
show you how to turn your template into an application and view your completed work.
6.4.1 Step-by-step: Adding users that can see the template
To add users that can see the template, perform the following tasks:
1. From the Template Library, click the key icon next to the template that you created
(Figure 6-10).
Figure 6-10 Key icon in the template library
2. On the next page, select Template Users. Click Add.
3. From the Directory Search window, add users that are allowed to create an application
based on this template.We used Nick Manager and Marc Manager. Click OK.
4. Click Close Template Roles.
152
IBM Workplace 2.5 Development with Workplace Designer
6.4.2 Step-by-step: Instantiating an application from the template
To instantiate an application from the template:
1. Log in to Workplace Collaboration Services as one of the users you added previously.
2. Click Team Collaboration → Team Spaces → New.
3. Make your team space unique to the team that you are creating it for. For example, we
called ours Nick Manager’s Team.
4. Choose the Team Tracking template, and assign it a description.
5. Click OK to access the Team Spaces Component Properties page shown in Figure 6-11.
Figure 6-11 Team Spaces Component Properties page
6. At this point, you can again change the component parameters for the Status Report
component to be elements that might be unique to this specific deployment. For example,
add an additional expense category, Cell Phone.
7. Click OK.
8. Open the new Team Space.
9. On the Team Project home page (Figure 6-12 on page 154), you can add the users that
need to create reports to the list of team members.
Chapter 6. Templates
153
Figure 6-12 Team Project view
10.Click the Status Reports page to see your component as a part of this overall application
(Figure 6-13).
Figure 6-13 Team manager initial view
11.Add some task categories.
12.Log out.
13.Log back in as a user and create status reports.
What a team member sees
Figure 6-14 on page 155, Figure 6-15 on page 156, and Figure 6-16 on page 157 show the
pages that a team member sees.
154
IBM Workplace 2.5 Development with Workplace Designer
Figure 6-14 Team member view
Chapter 6. Templates
155
Figure 6-15 Member report form
156
IBM Workplace 2.5 Development with Workplace Designer
Figure 6-16 Member view after adding reports
What a team manager sees
Figure 6-17 illustrates what a team manager sees.
Figure 6-17 Team manager view
Chapter 6. Templates
157
158
IBM Workplace 2.5 Development with Workplace Designer
A
Appendix A.
Workplace Designer for Domino
developers
The tables in this appendix are provided for developers who are familiar with Lotus Domino
Designer and programming for a Lotus Domino server. These tables are not a full listing of
features in either Workplace Designer or Domino Designer. The purpose of these tables is to
help to map some of the concepts that you are familiar with in Domino to those similar
concepts in Workplace Designer.
© Copyright IBM Corp. 2005. All rights reserved.
159
Comparative tables with common Domino Designer functions
Table A-1 Forms
Feature
Domino Designer
Workplace Designer
Form design element
Yes
Yes
Fields
Fields represent both UI and
schema
UI Controls are bound to a
separate XML schema
Default field value
Default formula
Default value, may be
computed with JavaScript
Field validation
Validation @formula
Check box on control property
for content validation using
regular expressions
Check box on control for
Required value
Field input translation
@formula
JavaScript on control event
(onBlur, onChange)
Dynamic field values
@dbcolumn on keywords field
Lookups using JavaScript on
combo box or list box controls
Next page after submit
$$Return field
Form property, plus page after
failure occurs
Save doc when...
SaveOptions=0 or 1
Form property - Save only
when...<condition>
Visibility
Hide When...formula on
paragraphs
Visibility property on all UI
Controls and paragraphs
Authors, Readers fields
Yes
Editors, Readers fields
accessed programmatically
only
Read-only fields
Computed or Computed for
Display
Read-only property = true,
false, or computed
Tab order
Yes
Yes
Images
Yes, in-line or library
Yes, in library
Pass thru HTML
In line, text property
Computed field control - Value
property
Formatting
from properties panel
from Properties panel and CSS
Tables
Yes
Yes, UI control under Container
Controls
Feature
Domino Designer
Workplace Designer
Views
Separate design element
UI Control
Document selection
@formula, simple
By schema, plus queries and
runtime filters available
Embedded views
Yes
Yes (default), can have multiple
views on a page
Table A-2 Views
160
IBM Workplace 2.5 Development with Workplace Designer
Feature
Domino Designer
Workplace Designer
Sorting
Yes, on column property
Yes, by column on View
property
Categorized views
Yes
Yes
Response hierarchy
Yes
Yes
Calculate column values
Yes, @formulas
Yes, JavaScript
Pass-through HTML
Yes
Yes, on columns
Column images
Yes
Yes
Column events
No
Yes (2.6)
Computed columns
Yes
Sum, Count, Average,
Minimum, Maximum
Lookups
Yes
Yes, by JavaScript formula or
dialog box to another view
Access programmatically
Yes
Yes
Shared columns
Yes (Designer 7.0)
No
Paging navigator
No
Yes
Live names on columns
Yes
Yes (2.6)
Hide columns
Yes
Yes
Formatting
via properties panel
by Properties panel and CSS
Action bar
Yes
No, use buttons or links on the
form
Calendar view
Yes
No
Feature
Domino Designer
Workplace Designer
Data storage
NSF
XML in RDBMS
Design storage
NSF, NTF
File system
Feature
Domino Designer
Workplace Designer
Server programming language
@formulas, LotusScript, Java,
C, C++
JavaScript, Java, @function
emulation layer in JavaScript
Client programming language
@formulas, LotusScript,
JavaScript
JavaScript
Simple Actions
Yes
Yes
Script Libraries
Yes
Yes
Agents
Yes
No
Field events
Yes
Yes
Table A-3 Database storage
Table A-4 Programming
Appendix A. Workplace Designer for Domino developers
161
Feature
Domino Designer
Workplace Designer
Form events
Yes
Yes
Database events
Yes
No
Component events
No
Yes
Object model libraries
Domino Objects: session,
database, document, view,
document collections, items
DocAPI: session, database,
document, view, document
collections, fields, XML DOM,
Workplace APIs
Feature
Domino Designer
Workplace Designer
Document format
NSF CD records
XML
Schemas
Embedded in NSF
XSD Schemas and Editor
included
Document hierarchy
Flat
Yes, unlimited levels
Deployment
Copy/replicate NSF or NTF to
Domino server
Deploy portlet and database
definitions to server; one-click
deployment for testing
Field encryption
Notes client only
No
Table A-5 Other features
162
IBM Workplace 2.5 Development with Workplace Designer
B
Appendix B.
Application-specific tips and
resources
This appendix provides you with some tips and recommendations for working on a single
component with a team using Workplace Designer.
© Copyright IBM Corp. 2005. All rights reserved.
163
Collaborative development in Workplace Designer 2.5
Starting development
When it is time to start development:
򐂰 Begin by creating common components on a single machine:
– Schemas
– Skeletons of forms
– Script libraries
򐂰 Export the component to all developers.
Merging changes
Three tips for handling the complexities of merging changes are:
򐂰 Before you modify a component, be sure to save a deprecated version to a subdirectory.
򐂰 Add the changes to the master version of the component.
򐂰 One person should physically modify a single file at a time.
Deploying
Some tips for deployment are:
򐂰 Do not import a component (portlet) to Workplace Designer and deploy it with the same
name as an existing portlet in the Workplace Collaboration Services portlet catalog
because then you have two portlets with the same name in the catalog. Before
deployment, rename the component using the Workplace Designer import dialog or
provide the component with a different name using the label field for the component, which
is found in the Basics tab for the component.
򐂰 If you do not set a label name for the component, the name of the component becomes
the portlet name in the portlet catalog.
򐂰 Some server problems can be fixed by deleting components from the server and
re-deploying, or by re-deploying with a new component name.
More tips
A few more useful tips for collaboration are:
򐂰 Use the Error tab of Workplace Designer. Click File → Preferences... → Property Tab.
򐂰 If you experience problems while deploying a component, review the SystemErr.log and
SystemOut.log files of the local Workplace Designer installation directory for more
information.
򐂰 Use print() and _dump statements to debug your code. Print() statements are written to
the SystemOut.log of the portal server.
򐂰 When you want to use multiple combo boxes on a single page, change focus when moving
between values tabs.
򐂰 Sometimes exporting or importing the component fixes problems.
164
IBM Workplace 2.5 Development with Workplace Designer
C
Appendix C.
Additional material
This Redpaper refers to additional material that can be downloaded from the Internet as
described below.
Locating the Web material
The Web material associated with this Redpaper is is available in soft copy on the Internet
from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/REDP4090
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select Additional materials and open the directory that corresponds with the Redpaper form
number, REDP4090.
Using the Web material
The additional Web material that accompanies this Redpaper includes the following files:
Table 6-1 Sample code
File name
Description
RedpaperComp_Ch3.jar
Sample code used for Chapter 3
RedpaperComp_Ch4 .jar
Sample code used for Chapter 4
RedpaperComp_Ch5 .jar
Sample code used for Chapter 5
WD25_install_EN.pdf
Installation Guide for installing Workplace
Designer 2.5
© Copyright IBM Corp. 2005. All rights reserved.
165
How to use the Web material
Create a subdirectory (folder) on your workstation, and unzip the contents of the Web
material zip file into this folder.
166
IBM Workplace 2.5 Development with Workplace Designer
Related publications
The publications listed in this section are considered particularly suitable for a more detailed
discussion of the topics covered in this Redpaper.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks” on page 167.
Note that some of the documents referenced here might be available in soft copy only.
򐂰 IBM Workplace Collaboration Services: Release 2.5 Deployment Guide, SG24-6777
Online resources
These Web sites and URLs are also relevant as further information sources:
򐂰 IBM Workplace Designer Homepage
http://www-128.ibm.com/developerworks/workplace/products/designer/
򐂰 Workplace Designer product documentation
http://www-128.ibm.com/developerworks/workplace/documentation/designer/
How to get IBM Redbooks
You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft
publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, 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. 2005. All rights reserved.
167
168
IBM Workplace 2.5 Development with Workplace Designer
Back cover
IBM Workplace 2.5
Development with
Workplace Designer
Overview of
Workplace Designer
features and benefits
Creating a component
and using the design
elements
Building a sample
application
IBM Workplace Designer is an intuitive visual development tool that
allows application developers, designers, and others to easily create
and deploy components for the IBM Workplace environment. IBM
Workplace Designer Version 2.5 features a visual design interface and
powerful scripting capabilities that are familiar to Domino application
developers and are intuitive to Microsoft Visual Basic developers and
other script developers. It is based on Eclipse and supports a
service-oriented architecture (SOA), incorporating the following industry
standards:
- XML for data access and exchange
- Java 2 Enterprise Edition (J2EE)
- HTML/CSS for portal development
- JavaScript for the programming language
This Redpaper provides an overview of the features and functionality of
IBM Workplace Designer 2.5 and shows application developers how to
build applications for IBM Workplace Collaboration Services 2.5 and IBM
Workplace Services Express 2.5. We introduce a sample status tracking
application, and show you the specific step-by-step development
techniques that you can use to build the component. We discuss
specific design elements in depth within the context of building the
sample application and provide best practices, hints, and tips for
collaborative development with Workplace Designer.
®
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.
The audience for this Redpaper is primarily application developers with
a background in Java, Domino development, Javascript, or other visual
scripting languages.
For more information:
ibm.com/redbooks