Sei sulla pagina 1di 536

DISCLAIMER

THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED AS IS WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

COPYRIGHT
Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Lotus Development Corporation, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software. Copyright 1985 1999 Lotus Development Corporation 55 Cambridge Parkway Cambridge, MA 02142

All rights reserved. Printed in the United States.

LIST OF TRADEMARKS
Domino, cc:Mail, Notes, NotesBench, NotesFlow, and Notes/FX are trademarks and Freelance, Freelance Graphics, Lotus, Lotus Components, Lotus Notes, LotusScript, Notes Mail, NotesSQL, NotesView, 1-2-3, Organizer, SmartIcons, and SmartSuite are registered trademarks of Lotus Development Corporation. AS/400, OS/2 Warp, RS/6000, and PowerPC are trademarks and AIX, IBM, OS/2, Presentation Manager, and SNA are registered trademarks of International Business Machines Corporation. Tivoli/Courier is a trademark of Tivoli Systems Inc., a wholly owned subsidiary of International Business Machines Corporation. All other trademarks are the property of their respective owners.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . xi 1 Introduction to Domino Designer . . . . . . . . . . . . . . . 1
Overview applications and databases . . . . 1 Starting Designer . . . . . . . . . . . . . . . . . . . . . . 3 Exploring Designer . . . . . . . . . . . . . . . . . . . . 4 Displaying, collecting, and storing information pages, forms, documents, and fields . . . . . . . . . . . . . 6 Organizing your data views and folders . . . . . . . . . . . . . . . . . . . . . Creating navigation outlines and navigators . . . . . . . . . . . . . . . . . . Structuring your display framesets .... Adding automation actions, hotspots, and agents . . . . . . . . . . . . . . . . . . . . . Getting database information design synopsis . . . . . . . . . . . . . . . . . 10 11 12 13 14 Settings for multilingual applications . . . HTML tag attributes for a Domino server . . . . . . . . . . . . . . . . . . Hide-when options . . . . . . . . . . . . . . . . . Enabling subscriptions . . . . . . . . . . . . . . Reducing database maintenance with shared resources . . . . . . . . . . . . . . . . Creating an image resource . . . . . . . . . . . . . Designing an application for maximum accessibility for people with disabilities . . . . . . . . . . . . . . . . . Previewing your design work . . . . . . . . . . . 27 28 29 30 30 31

35 37

3 Designing Outlines . . . . . . . . .
Outlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an outline . . . . . . . . . . . . . . . . . Embedding an outline .............. Outline, outline entry, and embedded outline properties . . . . . . . . . . . . . . . . Selected outline properties . . . . . . . . . . . Selected outline entry properties ...... Selected embedded outline properties . . . . . . . . . . . . . . . . Using the outline applet ............... Displaying the outline in a Frameset . . . . . .

41
41 42 45 46 46 46 47 51 52

2 Creating an Application . . . . .
Domino databases . . . . . . . . . . . . . . . . . . . . Creating databases ................... Creating a database from a template . . . . . . Copying an existing Domino database . . . . Starting a database from scratch . . . . . . . . . Tips for designing Web applications . . . . . . Domino Applets ..................... Changing database and design properties . . . . . . . . . . . . . . . . . . . . . . Setting Use JavaScript when generating pages for a database . . . . Setting database launch properties . . . . .

15
15 16 16 18 20 21 22 23 23 25

4 Designing Pages . . . . . . . . . . .
Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a page . . . . . . . . . . . . . . . . . . . . Displaying a page . . . . . . . . . . . . . . . . . . Creating a home page for an application . . . . . . . . . . . . . . . . . . Styling text for the Web .............

53
53 55 55 56 57

Contents iii

Creating computed text

.............

58 58 59 60 61 62 64 68 69 70 71 71 73 74 75 75 75

Layout regions . . . . . . . . . . . . . . . . . . . . . . . Aligning and rearranging elements in a layout region . . . . . . . . . . . . . . . Changing the size and style of a layout region . . . . . . . . . . . . . . . . . . Adding a graphic to a layout region . . . Embedded Controls . . . . . . . . . . . . . . . . . . Adding a file upload control . . . . . . . . . Adding a group scheduler . . . . . . . . . . Profile forms . . . . . . . . . . . . . . . . . . . . . . . Designing forms that prompt users for input . . . . . . . . . . . . . . . . . . . . . . Designing a form that presents a dialog box . . . . . . . . . . . . . . . . . . . . Designing a form that prompts users for information . . . . . . . . . . . . . . . . . Designing a form that lets users make selections from a view . . . . . . Designing a form for a Domino billing application . . . . . . . . . . . . . . Customizing Form processed confirmation for the Web . . . . . . . . . Customizing search forms . . . . . . . . . . . . . Tips for improving document display time . . . . . . . . . . . . . . . . . . . Testing a form before deploying it . . . . . . .

99 100 100 101 102 102 102 106 108 108 109 110 111 112 113 118 119

Changing all text styles . . . . . . . . . . . . . . Creating and formatting horizontal rules . . . . . . . . . . . . . . . . . Creating programmable tables . . . . . . . . Creating sections . . . . . . . . . . . . . . . . . . . Creating links . . . . . . . . . . . . . . . . . . . . . Adding graphics . . . . . . . . . . . . . . . . . . . Adding a background color or graphic . . . . . . . . . . . . . . . . . . . . . . Creating an imagemap . . . . . . . . . . . . . . Adding an applet . . . . . . . . . . . . . . . . . . Creating an attachment . . . . . . . . . . . . . . Embedding elements ............... Importing, pasting, or entering HTML . . . . . . . . . . . . . . . . . Launch properties for pages or forms . . . . . . . . . . . . . . . . . . . . . . . Programming a page or form Adding JavaScript header information ........... .... Adding HTML header information

..............

5 Designing Forms . . . . . . . . . . .
Forms ............................. Form Elements . . . . . . . . . . . . . . . . . . . . . . . Forms and documents . . . . . . . . . . . . . . . . . Creating a form . . . . . . . . . . . . . . . . . . . . . . Tips for designing forms . . . . . . . . . . . . . Naming forms . . . . . . . . . . . . . . . . . . . . . Making a form available to Web browsers . . . . . . . . . . . . . . . . . . Selected form properties . . . . . . . . . . . . . . . Creating a response hierarchy ........ Version tracking . . . . . . . . . . . . . . . . . . . Customizing a forms window title . . . . . . . Subforms . . . . . . . . . . . . . . . . . . . . . . . . . . .

79
79 80 81 84 85 86 88 90 92 93 95 97

6 Designing Fields . . . . . . . . . .
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a shared field Field names and labels ............... ............... ............

121
121 122 124 125 126 126 128 129 133

Defining field types . . . . . . . . . . . . . . . . . . Text and rich text fields Rich text fields on the Web . . . . . . . . . . Number fields . . . . . . . . . . . . . . . . . . . . Date/Time fields . . . . . . . . . . . . . . . . . . Formulas for Date/Time fields . . . . . . .

iv Application Development with Domino Designer

Creating a graphical display for Date/Time fields . . . . . . . . . . . . . . . Names fields . . . . . . . . . . . . . . . . . . . . . Readers and Authors fields ......... Creating fields to display lists of choices . . . . . . . . . . . . . . . . . . . . . Generating choices for lists . . . . . . . . . . Creating aliases for choices in a list ... Password fields . . . . . . . . . . . . . . . . . . . Formula fields . . . . . . . . . . . . . . . . . . . . Editable and computed fields . . . . . . . . . . Editable field formulas . . . . . . . . . . . . . Selected Field Properties . . . . . . . . . . . . . . Hiding fields . . . . . . . . . . . . . . . . . . . . . . . Creating a field in a layout region . . . . . . . Adding HTML attributes to a field . . . . . . Storing HTML in a field . . . . . . . . . . . . . . . Creating fields that inherit values . . . . . . . Creating a field that inherits an entire document . . . . . . . . . . . . . . . . Inheriting information in a response hierarchy . . . . . . . . . . . . . . Standard fields used in templates . . . . . . . Predefined fields with built-in functionality ............

133 136 137 137 139 140 142 144 146 148 151 153 155 156 157 157 158 159 160 160 162 164

8 Designing Views . . . . . . . . . .
Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard views . . . . . . . . . . . . . . . . . . . Calendar views . . . . . . . . . . . . . . . . . . . Shared and private views Naming a view Columns ............. Creating a view . . . . . . . . . . . . . . . . . . . . . ..................... ..........................

173
173 174 176 178 179 181 184 184 185 186 187 189 191 194 197 200 201 204 205 205 205 206 207 210 210 210

Adding titles to columns . . . . . . . . . . . . Adding categories to views . . . . . . . . . . Categorizing in the All by Category view . . . . . . . . . . . . . . . . . Generating category names ......... Programming which documents display in a view . . . . . . . . . . . . . . . Table of document selection conditions for views . . . . . . . . . . . . . . . . . . . . . Adding programming to columns . . . . . . . Table of simple functions for columns . . . . Displaying an icon in a column . . . . . . . . . Sorting documents in views ........... Overriding alphabetical sorting with a hidden column . . . . . . . . . . . . . . . . . Customizing which column links to Web documents . . . . . . . . . . . . . . . . Adding pass-thru HTML to a column . . . . Using a column to switch to another view . . . . . . . . . . . . . . . . . . Generating column totals, averages, and percents . . . . . . . . . . . . . . . . . . . Table of view, row, and column styles ... Using HTML formatting for views and columns . . . . . . . . . . . . . . . . . . . Default views . . . . . . . . . . . . . . . . . . . . . . . Defining what users see when they open views . . . . . . . . . . . . . . . . . . . .

Fields for version tracking . . . . . . . . . . . . . Fields that prompt users to select folders . . . . . . . . . . . . . . . . . .

7 Designing Framesets

.....

165
165 166 168 170 171 172

Overview of framesets . . . . . . . . . . . . . . . . Creating a frameset . . . . . . . . . . . . . . . . . . Providing content for a frame . . . . . . . . . . Setting the style for frames ............ Launching a database into a frameset . . . . Launching a document or page into a frameset . . . . . . . . . . . . . . . . . . . . .

Contents v

Formulas that look for values in columns and views . . . . . . . . . . . . . Indenting response documents . . . . . . . . . Formulas for response columns . . . . . . . . . Displaying views in Web applications . . . . . . . . . . . . . . . View applet . . . . . . . . . . . . . . . . . . . . . . . . Creating an embedded view or embedded folder pane . . . . . . . . . . . Show single category in embedded views . . . . . . . . . . . . . . . Setting line counts in embedded views . . . . . . . . . . . . . . . Hiding a view . . . . . . . . . . . . . . . . . . . . . . Identifying unread documents ......... Formatting date and time columns . . . . . . . . . . . . . . . . . . Displaying numbers in columns . . . . . . . . Refreshing view indexes . . . . . . . . . . . . . . Designing folders ................... Designing a form as a view or navigator template . . . . . . . . . . . . . .

211 213 214 215 216 218 220 221 221 222 223 224 225 227 228

Embedding navigators in a form, subform, page, or document

......

240 241 241 242

Overriding an embedded navigator with a navigator template . . . . . . . . Importing a navigator into a form, subform, page, or document ......

Testing navigators . . . . . . . . . . . . . . . . . . .

10 Automation in Applications . . . . . . . . . . . . . .
Automation . . . . . . . . . . . . . . . . . . . . . . . . Actions Hotspots ........................... ..........................

245
245 246 247 248 249 253 257 258 260 261 262 263 265 266 267 269 271

Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an unshared form action or view action . . . . . . . . . . . . . . . . . . . . Action bar . . . . . . . . . . . . . . . . . . . . . . . . . Creating and inserting shared actions . . . . Creating a link . . . . . . . . . . . . . . . . . . . . . . Creating a button . . . . . . . . . . . . . . . . . . . . Creating a text pop-up . . . . . . . . . . . . . . . . Creating a formula pop-up . . . . . . . . . . . . Creating an action hotspot . . . . . . . . . . . . . Creating a program for an event . . . . . . . . Building an agent ................... Options for running agents . . . . . . . . . . . .

9 Designing Navigators . . . . . .
Navigators . . . . . . . . . . . . . . . . . . . . . . . . . Creating a navigator . . . . . . . . . . . . . . . . . Adding graphic objects to navigators . . . . Adding and enhancing graphics in a navigator . . . . . . . . . . . . . . . . . . Adding text to and highlighting a navigator object . . . . . . . . . . . . . . . . Adding hotspots to navigators . . . . . . . Automating navigators . . . . . . . . . . . . . . . Navigators, imagemaps, and outlines . . . . Displaying a navigator when users open a database . . . . . . . . . . . . . . . . . . . . Hiding navigators . . . . . . . . . . . . . . . . . . .

229
229 230 231 232 233 234 234 238 239 239

Selecting where to run a scheduled agent . . . . . . . . . . . . . . . Examples of agents to run before Web users open or save documents . . . . . . . . . . . . . . . . . . . . Setting up agent security . . . . . . . . . . . . . .

272 273

vi Application Development with Domino Designer

Troubleshooting agents . . . . . . . . . . . . . . . Simulating the running of an agent ... Agent Log . . . . . . . . . . . . . . . . . . . . . . . Notes server console commands . . . . . . Agent Manager debugging information AgentRunner ..........

277 278 279 280 282 283 284 287 291 292 294 295 296 299 299 300 302

Selecting, running, deleting, and copying applets . . . . . . . . . . . . . . . . Refreshing and exporting applet files . . . . . . . . . . . . . . . . . . . . Setting security for applets . . . . . . . . . . Saving applet data ................ Tips and troubleshooting for Java applets . . . . . . . . . . . . . . . . . . .

313 314 314 317 320

NotesLog Class . . . . . . . . . . . . . . . . . . . .................... Simple actions for automation components . . . . . . . . . . LotusScript for automation components . . . . . . . . . . . . . . . . . . . Restricted LotusScript and Java agent operations . . . . . . . . . . . . . . . . Formulas for automation components . . . . JavaScript for automation components . . . Table of supported JavaScript objects for automated components . . . . . . . Importing Java programs ............. ...... Creating Java programs for agents

12 Including OLE Objects in Applications . . . . . . . . . . . . .


Designing applications using OLE ...... Linking and embedding objects in forms . . Adding OLE custom controls to a form . . . . . . . . . . . . . . . . . . . . . . . . Modifying a form to size an embedded object . . . . . . . . . . . . . . . Modifying a form so that it sizes an OLE custom control or JavaBean . . . Modifying a form to run a custom control or JavaBean in Read mode . . Letting documents update objects created by forms . . . . . . . . . . . . . . . Launching objects automatically . . . . . . . . Designing a form that launches an object automatically . . . . . . . . . . . . . Designing a form that launches a new object automatically . . . . . . . . . Launching an object in-place or out-of-place . . . . . . . . . . . . . . . . . . . Specifying the event that causes an object to autolaunch . . . . . . . . . . . . Designing a form for documents that open as modal dialog boxes . . . . . . . Designing a form to hide the Notes document . . . . . . . . . . . . . . . . Hiding an embedded object in a document . . . . . . . . . . . . . . . . . . .

325
325 327 328 329 330 331 331 331 333 334 335 336 337 337 339

Actions and agents names . . . . . . . . . . . . . Hiding automated components . . . . . . . . .

11 Including Java Applets in Applications . . . . . . . . . . . . .


Java applets overview . . . . . . . . . . . . . . . . Enabling Java applets ................ Importing an applet . . . . . . . . . . . . . . . Linking to an applet on the Web . . . . . . Setting applet parameters . . . . . . . . . . . . . Setting applet parameters, attributes, and properties . . . . . . . . . . . . . . . . . Setting HTML attributes . . . . . . . . . . . . Setting Alternate HTML attributes . . . . Setting properties . . . . . . . . . . . . . . . . . Setting up shared applet resources . . . .

303
303 304 305 306 307 308 309 309 310 312

Contents vii

Publishing actions . . . . . . . . . . . . . . . . . . . Exchanging data using Notes/FX . . . . . . . Preparing a form to exchange data . . . . . .

340 342 343

Encrypting documents automatically . . . . . . . . . . . . . . . . . . Creating a field that generates a list of secret encryption keys . . . . . . . . . Restricting who can edit a section . . . . . . . Restricting who can access a section of a document . . . . . . . . . . . . . . . . . . . Attaching electronic signatures to documents and sections in Notes applications . . . . . . . . . . . . . . How Designer stores and verifies electronic signatures in Notes applications . . . . . . . . . . . . . .

365 366 368 369

13 Restricting Access to and Securing Parts of an Application . . . . . . . . . . . . . .


Security in an application ............. Controlling access to a database during design . . . . . . . . . . . . . . . . . . Enforcing encrypted Web transactions using SSL . . . . . . . . . . . . . . . . . . . . . Restricting access to documents ........ Restricting who can see a view or folder . . Restricting who can update the contents of a folder . . . . . . . . . . . . . . Restricting access to all documents created from a form . . . . . . . . . . . . . Restricting who can create or read all documents from a form . . . . . . . . . . Preventing printing, forwarding, and copying of documents . . . . . . . . . . . Using a Readers field to restrict access to specific documents . . . . . . . . . . . . Using an Authors field to restrict who can edit specific documents . . . . . . . Restricting who can read or edit specific documents . . . . . . . . . . . . . . Tracking who edits a document ........ Restricting authors from changing fields in existing documents . . . . . . . . . . . Creating pages, forms, outlines, views, and agents for public access . . . . . . . Encrypting documents in Notes applications . . . . . . . . . . . . . . Encrypting documents . . . . . . . . . . . . . Creating a secret encryption key . . . . . . . . . . . . . . . . .

347
347 349 350 351 351 353 353 354 355 355 356 356 359 360 360 361 363 364

371

372

14 Completing an Application and Managing Design Changes . . . . . . . . . . . .


Completing an application ............ Creating a database icon for a Notes application . . . . . . . . . . . . . . . Providing online help for an application . . Creating About and Using documents for a database . . . . . . . . . Creating context-sensitive help for an application . . . . . . . . . . . . . . . . . Writing help for fields ............. Creating and displaying more detailed application help . . . . . . . . . Specifying the Web site home page in the Server document . . . . . . . . . . . . Restricting design changes ............ Checking the application design before rollout . . . . . . . . . . . . . . . . . . Checking form design . . . . . . . . . . . . . . . . Checking field design . . . . . . . . . . . . . . . . Checking view design ............... Making a design copy of a completed application . . . . . . . . . . .

375
375 375 377 377 379 380 381 382 383 383 384 385 386 388

viii Application Development with Domino Designer

Pilot testing an application

............

389 391 391 391 393 394 395 397 398 401 402 402 403 404 406 407 408 409 411

Using an agent to mail notices . . . . . . . Using an agent to send announcements . . . . . . . . . . . . . . . .

422 423

Renaming a database . . . . . . . . . . . . . . . . . Renaming design elements . . . . . . . . . . Design synopsis . . . . . . . . . . . . . . . . . . . . . Updating documents after redesigning a form . . . . . . . . . . . . . . . . . . . . . . . . Checking field values in a document . . . . . Using agents to update documents affected by form changes . . . . . . . . . Templates ......................... Creating templates . . . . . . . . . . . . . . . . . . . Creating a design library template . . . . Linking a database to a template ..... Linking individual design elements to a template . . . . . . . . . . . . . . . . . . Making and distributing design changes . . . . . . . . . . . . . . . . . Refreshing a design . . . . . . . . . . . . . . . . . . Replacing a design . . . . . . . . . . . . . . . . . . . Design changes and replication . . . . . . . . . Preventing design changes . . . . . . . . . . . . Hiding the design of a database ........ Hiding design elements . . . . . . . . . . . . . . .

16 Connecting to Enterprise Data . . . . . . . . . . . . .


Accessing data in enterprise applications . . . . . . . . . . . . . . . . . . . Using ODBC to access relational databases . . . . . . . . . . . . . Registering data sources for ODBC . . . . . . . . . . . . . . . . . . . . . Writing formulas and scripts to access relational databases . . . . . . . .

425
425 428 429 430

17 Including Java Servlets in Web Applications . . . . . . . . .


Overview of Java servlets ............. Comparing agents, servlets, and CGI programs . . . . . . . . . . . . . . . . . Running servlets in Domino . . . . . . . . . . .

431
431 432 434

Appendix A Domino Designer Templates . . . . . . . . . Appendix B Importing to and Exporting from Views . . . . Appendix C Developing Applications Using MAPI . . . . . Appendix D Features to Avoid Using in Web Applications . . . . . . . . . . . . . . . . Appendix E Programming a Web Site . . . . . . . . . . . . . . . . . Index . . . . . . . . . . . . . . . . . . . . . .

441 443 455

15 Creating a Workflow Application . . . . . . . .


Workflow Overview . . . . . . . . . . . . . . . . . Planning workflow . . . . . . . . . . . . . . . . . . Features that support automatic mailing . . Enabling users to view documents ...... Mailing features and Web applications . . . Fields that control mailing options . . . . . . Displaying the MailSend dialog box . . . . . Creating a database that receives mailings . . . . . . . . . . . . . . . Using an agent to send automatic replies . . . . . . . . . . . . . . .

413
413 414 415 416 417 417 421 421 422

463 475 503

Contents ix

Preface
This guide describes how to create all the design elements used in building Domino applications, how to share information with other applications, and how to customize applications. This guide is intended for developers who are creating applications with Domino Designer.

Structure of this guide


This guide consists of 17 chapters and 5 appendixes: Chapter 1, Introduction to Domino Designer, provides an overview of the Designer user interface and a brief introduction to key product features and design elements. Chapter 2, Creating an Application, provides an overview of creating applications along with some design considerations. Chapter 3, Designing Outlines, shows you how to create and format an outline, and how to embed an outline on a form or page to use as a navigational structure for your application. Chapter 4, Designing Pages, describes designing pages for Web and Notes applications. Chapter 5, Designing Forms, describes designing forms and includes information on designing some special types of forms. Chapter 6, Designing Fields, describes how to create fields to collect and store specific types of information. Chapter 7, Designing Framesets, introduces frames and framesets, which can add structure to your application. Chapter 8, Designing Views, describes how to design views, which help users find the documents they want and also serve as summaries of the database contents. Chapter 9, Designing Navigators, explains how to create graphical navigators that help users find documents and use the database. Chapter 10, Automation in Applications, explains how to add automation features to an application to make it easier to perform tasks in the background.
xi

Chapter 11, Including Java Applets in Applications, describes adding Java applets to forms, documents, and pages. Chapter 12, Including OLE Objects in Applications, illustrates ways to design applications that use OLE technology to integrate data from other applications. Chapter 13, Restricting Access to and Securing Parts of an Application, briefly describes Designer features for limiting access to parts of an application. Chapter 14, Completing an Application and Managing Design Changes, describes how to document an application and how to test it before deployment, as well as how to make, control, and distribute design changes to applications that are already in use. Chapter 15, Creating a Workflow Application, describes how to create a workflow application by using automatic mailing features. Chapter 16, Connecting to Enterprise Data, briefly describes tools and techniques for connecting a Designer application to enterprise data. Chapter 17, Including Java Servlets in Web Applications, describes creating and running Java servlets on a Domino Web server. Appendix A, Domino Designer Templates, lists the templates available with Domino Designer that are specifically intended for use by application developers. Appendix B, Importing to and Exporting from Views, provides tips and restrictions on moving data to and from views. Appendix C, Developing Applications Using MAPI, provides information on the available support for accessing Notes mail files. Appendix D, Features to Avoid Using in a Web Applications, identifies features that are not applicable to Web browsers or are not yet supported for them. Appendix E, Programming a Web Site, contains information about using Domino URL commands for programming related to Web applications, such as formulas, Java, JavaScript, Perl and CGI scripting, and Visual Basic script.

xii Application Development with Domino Designer

Structure of Notes and Domino documentation


Documentation for Notes and Domino is provided online in three databases available from the Help menu: Notes 5 Client Help Domino 5 Administration Help Domino 5 Designer Help In addition, the Administration and Designer documentation is available as printed books. In Notes, select File - Other Help to see a table of all the available documentation. You can order books from the Lotus Web site at: www.lotus.com/store.

Documentation for the Notes Client


In addition to the online Help, the printed book Notes Step by Step provides a tutorial for beginning Notes users.

Documentation for Domino Administration


The following table shows the printed books that comprise the Domino Administration documentation set. The information in these books is also found in the Domino 5 Administration Help online database. Moving to Notes and Domino Release 5 Describes how to upgrade existing Domino servers and Notes clients to Release 5. Also describes how to move users to Domino from other messaging systems. Explains how to configure a specific network to work with Domino. Also illustrates how to run Notes using multiple network protocols and individual protocols, such as AppleTalk, Banyan VINES, NetBIOS, Novell SPX (NetWare), and TCP/IP. Describes how to set up and manage servers, users, server connections, mail, replication, security, calendars and scheduling, Web servers, NNTP services, billing, and system monitoring. Describes how to troubleshoot system problems. Describes how to set up, manage, and troubleshoot Domino clusters.

Configuring the Domino Network

Administering the Domino System, Volumes 1 and 2

Administering Domino Clusters

Preface xiii

Managing Domino Databases

Provides information on managing databases, including putting databases into production, setting up access control lists and replication, and maintaining databases.

Documentation for Domino Designer


The following table shows the printed books that comprise the Domino Designer documentation set. The information in these books is also found in the Domino 5 Designer Help online database. Application Development with Domino Designer Explains how to create all the design elements used in building Domino applications, how to share information with other applications, and how to customize applications. Introduces programming in Domino Designer and describes the formula language, the @functions, and the @commands. Provides reference information on the LotusScript classes, which provide access to databases and other Domino structures. Provides reference information on the Java classes, which provide access to databases and other Domino structures. Describes the basic building blocks of LotusScript, how to use the language to create applications, an overview of the LotusScript programming language, and a comprehensive list of language elements. Provides information on how to set up Domino Connectors, how to utilize Domino Enterprise Connection Services (DECS) to access enterprise data in real-time, and reference material for programming with the LotusScript Extension for Domino Connectors. Provides information on managing databases, including putting databases into production, setting up access control lists and replication, and maintaining databases.

Domino Designer Programming Guide Volume 1: Formula Language Domino Designer Programming Guide Volume 2: LotusScript Classes Domino Designer Programming Guide Volume 3: Java Classes LotusScript Language Guide

Domino Enterprise Integration Guide

Managing Domino Databases

xiv Application Development with Domino Designer

Notes Help *
Step by Step

**

Release Notes

Administration Help

Setting up a Domino Server Moving to Notes and Domino Release 5 Configuring the Domino Network Administering Domino Clusters Administering the Domino System, Volume 1 Administering the Domino System, Volume 2

Managing Domino Databases

Designer Help

* not available in print ** print only

Application Development with Domino Designer Domino Objects Domino Designer Templates Guide Posters Domino Designer Programming Guide, Volume 1: Formula Language Domino Designer Programming Guide, Volume 2: LotusScript Classes Domino Designer Programming Guide, Volume 3: Java Classes LotusScript Language Guide Domino Enterprise Integration Guide

Preface xv

Chapter 1 Introduction to Domino Designer


Welcome to Domino Designer. Designer is an integrated application development environment which lets developers and Web site designers create, manage, and deploy secure, interactive applications for the Domino Server. To see whats new in Release 5, look for this icon. If you are new to Designer or just getting to know Release 5, this brief tour will introduce you to some of the features in Release 5.

Overview applications and databases


Applications
Domino applications let people share, collect, track, and organize information, using Lotus Notes or the Web. Domino applications can cover a wide range of business solutions, including: Workflow Applications that route information. Tracking Applications that monitor processes, projects, performance, or tasks. Collaboration Applications that create a forum for discussion and collaboration. Data Integration Applications that integrate with relational databases and transactional systems. Personalization Applications that produce dynamic content based on, for example, user name, user profile, access rights, or time of day. Globalization Applications that use Domino Global Workbench to produce global sites. Every Domino application starts with a Domino database. All Domino applications contain one or more Domino databases.

Databases
A database is the container for the data, logic, and design elements in your application. Design elements are building blocks you use to create your application. Design elements include: Pages Forms Outlines Navigators Views Folders Framesets Shared Resources Agents

Creating a database
There are three ways to create a database: Using a template. The fastest way to create a database is to use one of the Domino templates included with Designer R5. Designer includes templates for creating a variety of applications. Applications created using one of the Designer templates can be used as is or customized. To decide if there is a template that is right for you, see the Table of Domino Designer templates. Copying an existing database. If you have access to a database that already has all the elements you are looking for, you can copy the design and create a new database with the same features. Once you have created the database, you can customize it to meet your companys needs. Starting from scratch. If the database you need is unique, the best method for you is to start from scratch. When you create a database from scratch, you start with a blank or empty database and create all of the design elements. In order to begin creating your application, you need to start Designer.

2 Application Development with Domino Designer

Starting Designer
There are two ways to start Designer after starting the Notes client: From the Designer Icon From a database in the Notes client

To start Designer from the Notes client Designer icon


1. Start the Notes client. 2. Click the Designer icon on the bookmark bar on the left of the bookmark pane. After you start Designer you can open an existing database or start a new one. Once you open a database, either a new or existing one, you will be in the Designer Workspace. If you already have a database to work with, you can start Designer directly from that database.

To start Designer from an open database in the Notes client


You must have designer or manager access to the database in the ACL. 1. Open the database. 2. Choose View - Design. or 1. Right-click the database icon on the bookmark bar. 2. Choose Open in Designer.

Chapter 1: Introduction to Domino Designer 3

Exploring Designer
Building a great application requires the right tools. You can think of Designer as your workshop it contains all the tools you need to build a great application. Before you get started building, well explore the work area.
Tabbed windows Menu bar Design bookmarks Design list Design pane Work pane Design action buttons Properties box Preview button buttons

Item Menu bar Preview buttons Tabbed windows

Purpose Presents context-sensitive menus of Designer commands. Launches the browser of your choice to preview your work. Navigates among the open windows on your workspace.

Design action buttons Perform actions such as creating elements, saving, closing. Properties box button Opens the properties box for the active design element. Design pane Design bookmarks Design list Work pane Contains the Design bookmarks icons and the Design list. Opens lists of bookmarked applications. Takes you to Work pane of a design element or resource. Lists everything in the database for the currently selected design element in top level view. Once an element is opened, becomes the Work area for that element.

4 Application Development with Domino Designer

When you open a design element such as a page or form, you will be in the work area for that design element. In addition to items in the Designer Workspace, the Programmers pane appears.
Reference tab

Objects tab

Script area

Item Reference tab

Purpose The Reference tab of the Info List replaces the R4.x LotusScript browser window and is language-sensitive. The contents of the Reference tab change depending on the language selected. If you are editing in the Formula language, the window contains @Commands, @Functions and fields. If you are editing in LotusScript, the window contains LotusScript information. If you are editing in JaveScript, the window contains information about the Document Object Model. If you are editing in Java, the window contains Java-related information. The Objects tab of the Info List lets you navigate between objects and events in the Programmers pane. To work on an object, select it to expand its list of properties and events. If you select a property or event, the script area of the Programmers pane changes to show the code that describes it. Events and properties that are already programmed appear in a darker color. Enter formulas in the Script area. Formulas can be written in Formula language, LotusScript, JavaScript, or Simple Actions.

Objects tab

Script area

Chapter 1: Introduction to Domino Designer 5

Properties boxes
Properties boxes are tools for working the various pieces of your application. With them you can select or modify settings for the element you are working with. Properties boxes have tabbed panes, and each pane gives you access to different attributes or options. In most windows, rightclicking will open up the Properties box for that design element. You can also choose Design - <element> Properties from the menu.

Properties boxes are context-sensitive so you can leave them open on your workspace and they will change to reflect the element that you are working with. Collapse a Properties box by double-clicking the top of the box. When collapsed, some of the properties boxes become context-sensitive tool bars.

Displaying, collecting, and storing information pages, forms, documents, and fields
How you display, collect, and store information is an important part of any application. The design elements you use to accomplish these tasks are pages, forms and documents, and fields.

Pages
A page is a database design element that displays information. Pages are a familiar Web concept. Almost every Web site has a home page a page

6 Application Development with Domino Designer

that contains information about the company, graphics that enhance the page, and links that take you to other places within the site or elsewhere on the Web.

Pages can be used anytime you are displaying information to the user. Pages can contain: Text Tables Graphics Applets Embedded objects such as navigators Links Pages often work in conjunction with framesets to display graphics, site navigation, or applets. For more information on pages, see Designing Pages.

Forms and Documents


Forms, like pages, display information. Everything that can be done with a page can be done with a form. What sets forms apart from pages is that

Chapter 1: Introduction to Domino Designer 7

forms can be used to collect information. A form provides the structure for creating and displaying documents. Documents are the elements that store data in the database.

When you create a form in Designer, you can choose to have a user open the form in the Notes client from the Create menu. On the Web, you provide the user a button or action that opens the form. When the user fills out the information and saves it, the information is saved as a document. When a user opens the document, the document uses the form as a template to provide the structure for displaying the data. For more information on forms and documents, see Designing Forms.

8 Application Development with Domino Designer

Fields
Fields are the element that collect data. You can create fields only on forms. Each field on a form stores a single type of information. A fields data type defines the kind of information a field accepts.

You can create fields in the following data types: Text Date/Time Number Dialog List Checkbox Radio button Rich Text Authors Names Readers Password Formula You decide if a field is editable that is, populated by user input or calculated that is, based on formulas. You can also program fields to retrieve data from other Domino applications or from external sources. You can even create shared fields, which can be used in many forms within the same database. The information collected in fields is stored in documents. For more information, see Designing Fields.

Chapter 1: Introduction to Domino Designer 9

Organizing your data views and folders


Views and folders organize the documents in your database.

Views
A view is a sorted or categorized list of documents. Views are the entry point to the data stored in a database. Every database must have at least one view, although most databases have more than one view. Views select the documents they display programatically. You can create a view that shows all of the documents in your database or only some of the documents, based on a formula. Views can sort the documents they display by a field on the form, such as date, category, or author. You can create views that are hidden from users but organize your data so that other applications can retrieve the information from the documents. Views can have multiple columns that display any of the information contained in the document.

For more information, see Designing Views.

Folders
A folder is a container that stores documents. Folders have the same design elements as views, and you design folders in much the same way as a view. The difference between folders and views is that a view always has a document selection formula that collects and displays documents automatically. A folder remains empty until users or programs add documents to the folder. For more information on folders, see Notes 5 Client Help.

10 Application Development with Domino Designer

Creating navigation outlines and navigators


Every application needs to include a way to navigate from one place to another. When you create a database from scratch, Designer provides a default navigation structure called the Folder pane or Navigation pane. The Folder pane displays all the shared views and folders in the database. The Folder pane displays on the left pane of the Notes client and on the top left of a browser window. You can choose to use this navigation structure or design a different one.

Outlines
You can create an outline to customize the Folder pane of an application. An outline is the skeleton of your application: each outline entry represents a key piece of the application. An outline can include background graphics, custom icons, links, or actions. When the outline is embedded on a page or form, users can click on the outline entries, which will take them where you want them to go. The process of creating a navigation structure with an outline involves three steps: Create a new or default outline and create an outline entry for each piece of the application you want to include in the navigation structure or site map. Embed your outline on a form or page. Format the display of the embedded outline. You can include the page or form that the outline is embedded on in a frameset if you choose. You can also use an outline to plan your application before you create any design elements.

For more information, see Designing Outlines.

Chapter 1: Introduction to Domino Designer 11

Navigators
Navigators are graphical roadmaps that direct users to specific parts of a database. They let users find documents or take actions without having to open views. Navigators are like imagemaps. You can create hotspots on a graphic that take the users to links within or outside of your application. You can embed navigators on forms or pages. Navigators can take the place of the folder pane or work in conjunction with it. For more information on navigators, see Designing Navigators.

Structuring your display framesets


For an application interface to be intuitive and efficient, it must make good use of the users screen. One way for a designer to accomplish this is to use a frameset. A frameset is a collection of frames. A frame is one section, or pane, of the larger frameset and is independently scrollable. By using framesets, designers can create links and relationships between frames. Framesets provide the ability to leave one page displayed as users scroll or link to other pages or databases. There is no HTML required to design a frameset.

Designer lets you: Create an effective multi-paned user interface for your applications Control frame attributes such as size, scrolling, border colors and width, and frame spacing

12 Application Development with Domino Designer

Determine frame source content at runtime Create programmable links that are maintained automatically Set a frameset to launch automatically when a database, form, or page opens For more information on framesets, see Designing Framesets.

Adding automation actions, hotspots, and agents


Adding automation to an application can speed up repetitive tasks, route documents, update information, perform calculations, run programs, and check for errors. You add automated components to the design elements in a Domino application such as a database, a view, a form, or a document.

Actions
Actions automate tasks such as mimicking the Notes menus or tasks defined by formulas or a LotusScript program. Users click a button, hotspot, or pick from the Action menu to execute the action. In particular, use actions to simulate Notes menu items for web browser users.

Hotspots
A hotspot is text or a picture that a user can click to perform an action, run a formula or script, or follow a link. The hotspot can be a link to another web site, database, or element in a database; a button; a pop-up; or an action.

Agents
Agents are programs that perform a series of automated tasks according to a set schedule or at the request of a user. An agent consists of three components: when it acts (the trigger), what documents it acts on (the search), and what it does (the action). Use agents to set up user-activated tasks, or background tasks, in any part of a Domino application. Agents can be simple, such as moving documents to a folder, or complex, using Java programs to run multiple automated tasks at scheduled times. Agents are stored with databases, but you can use them to run automated tasks for views, documents, fields, and databases. For more information, see Adding Automation to Applications.

Chapter 1: Introduction to Domino Designer 13

Getting database information design synopsis


The design synopsis lets you generate a detailed report on a particular database. The design synopsis includes general information on the database such as size or access control lists as well as specific information about the design elements included in your database.

For more information, see Design synopsis.

Its time to build!


This completes the Designer tour. Its time for you to go exploring on your own. If you havent done so already, and youd like more help getting to know your way around the Designer tools, you can go through the Designer Guided Tour. Choose Help - Guided Tour to start it. Remember what you build with your tools can be as simple or as complex as you want. The Designer tools are at your disposal.

14 Application Development with Domino Designer

Chapter 2 Creating an Application


This chapter provides an overview of creating applications and includes design considerations and general information.

Domino databases
All Domino applications begin with a Domino database. Domino databases are the containers for your application. Databases hold the data, logic, and design elements for your application. Your Domino application can be made up of one or more Domino databases.

DATABASE

Design Elements: Pages, Forms, Views ...

DOCUMENT

Fields

Data Documents Field Type: Rich Text

FIELD Field Name: Body Data: 'Dear John ...'

With Designer, you create one application to use on both your intranet and the Internet. The structure of a database is the same whether for the Notes client or a Web browser. What makes a database a Web database is the viewing mechanism: users view it through a Web browser instead of the Notes client. You do all design work in Designer and use the same design elements forms, fields, views, outlines to display and organize the content.

15

Creating databases
There are three ways to create a new database: Using a template Copying an existing database Starting from scratch

Creating a database from a template


Designer comes with a collection of templates that you can use to create applications quickly. A template is a file that contains the structure for the database that is, pages, forms, and views but does not contain documents. For example, to design a discussion database, use the Discussion template (DISCSW50.NTF), which contains forms that track discussion threads in a hierarchy, as well as views that display the entries by date, author, or category. Designer templates have .ntf as their file extension. See Domino Designer Templates for a complete list of Designer Templates. Customizing a Template You can use a template as is or customize it for your organization. The templates that ship with Designer can be used as master templates. What makes a template a master template is that changes made to a master template can be passed along to all databases created from that template. Inheriting design changes from a master template can be initiated by the end user or by the Domino server, which runs a nightly Design task. You can disable this feature when you create your database by deselecting Inherit design from template. For more information on customizing a template, see Completing an application and managing design changes. To create a new database from a template After creating a database from a template, you may want to make changes to the database. Keep in mind that if you have selected Inherit design from template, changes you make to a database can be overwritten nightly by the Domino server design task or by refreshing the design of the database. If you plan to make design changes to the database and want to avoid the possibility of writing over design changes, deselect the database property Inherit design from template or protect individual design elements.

16 Application Development with Domino Designer

1. Choose File - Database - New. In the server field do one of the following: Leave Local selected to store the new database on your hard disk. Select or enter a server name to store the new database on a server. This allows multiple people to work on the database design. 2. In the Title field, enter a title for the new database. The Title can have a maximum of 32 characters. Note As you type a title, Designer adds a name to the File Name field. You can accept this database file name or change it. Database file names can be up to 8 characters and end with the file extension .nsf. If you plan to use the database you are creating as a template for other databases, use the file extension .ntf. 3. Select a template from the list. To display additional templates, do one following: Click Show advanced templates and select a template from the list. Click Template Server to use templates that reside on a server. 4. (Optional) Click Encryption, select Locally encrypt this database using:, select an encryption type, and click OK. For information on encrypting a database, see Notes and Domino encryption in Managing Domino Databases. 5. (Optional) If you are creating a database that will be on a Domino Release 4.x server, click Size limit and select a size (in gigabytes), and click OK. 6. (Optional) Click the Advanced tab and select the options that you want applied to your database. Click OK. For a description of the advanced options, see Managing Domino Databases. 7. Click OK. 8. (Optional) Choose File - Database - Properties, click the Design tab, and deselect Inherit design from template. This will prevent the new database from inheriting design changes from the master template whose design the database is based on.

Chapter 2: Creating an Application 17

Copying an existing Domino database


If you have found an application that contains all or most of the functionality you are looking for, you can copy the design of the database and use it as the basis for a new application. Before you copy the design of a database, check its Database Properties. If No design information is available is shown on the Database Properties box, the designer has hidden the design of the database, and you will never be able to modify the design of the new database. If you copy the design of an existing database, keep in mind that the settings for the full-text index are copied as part of the design. When you complete the new application, be sure to ask the database manager to create a new full-text index. For information on creating a full-text index for a database copy, see Setting up and managing full text indexes in Managing Domino Databases. You can use the new database as is, or you can modify it. Once you modify a database that you copied, protect your customized views, forms, subforms, navigators, shared fields, or agents. For more information on protecting design elements, see Preventing design changes.

To create a new database by copying an existing database


1. Open the database you want to copy. 2. Choose File - Database - New Copy. 3. In the server field do one of the following: Leave Local selected to store the new database on your workstation hard disk. Select or enter a server name to store the new database on a server. This allows multiple people to work on the database design. 4. (Optional) In the Title field, enter a title for the new database. The Title can have a maximum of 32 characters. Note When you copy a database, Designer automatically give the new database the same title and file name as the originally database. You can accept the database title and file name or change it. Database filenames can be up to 8 characters and end with the file extension .nsf. If you plan to use the database you are creating as a template, use the file extension .ntf rather than .nsf. 5. (Optional) Click Encryption, select Locally encrypt this database using:, select an encryption type, and click OK. For information on encrypting a database, see Notes and Domino encryption in Managing Domino Databases.

18 Application Development with Domino Designer

6. (Optional) If you are creating a database that will be on a Domino Release 4.x server, click Size limit and select a size (in gigabytes), and click OK. 7. Select Database design only so that the databases documents will not be copied to your new database. 8. Deselect Access Control List so that the original databases access control list will not be copied to your new database. 9. Click OK. 10. (Optional) Choose File - Database - Properties, click the Design tab, and deselect Inherit design from template. This will prevent the new database from inheriting design changes from the template whose design the database is based on.

To copy an individual design element


In addition to copying the entire design of a database, you can copy individual design elements. If there is a form, view, or other design element you would like in your database, copy it from the original database or template and paste it into your database. 1. Open the database or template containing the design element you want to copy. 2. From the Work pane, select the element or elements that you want to copy, such as a form or a view, and choose Edit - Copy. To select multiple elements, hold down the CTRL key while you are selecting the elements you want to copy. 3. Open the database where you want to paste the element or elements. 4. In the Design pane, click the type of element you are pasting, such as forms or views, and choose Edit - Paste. If your database inherits its design from a template, protect views, forms, subforms, navigators, shared fields, or agents that you copy into your database. To protect an individual design element 1. Select each design element in the Work pane. 2. Choose Design - Design Properties. 3. On the Design tab select Prohibit design refresh or replace to modify.

Chapter 2: Creating an Application 19

Starting a database from scratch


If you need a unique application, start from scratch. To do this, begin by creating a blank database. A blank database contains no design elements such as pages or forms. Blank databases have one default view. You must create all of the elements you need for the application. You begin by creating a database based on the -Blank- template. To create a new database from scratch To design a database from scratch, you must first create an empty database. Then design the forms, fields, views, and other design elements you will need for the application. 1. Choose File - Database - New. 2. In the Server field do one of the following: Leave Local selected to store the new database on your workstation hard disk. Select or enter a server name to store the new database on a server. This allows multiple people to work on the database design. 3. In the Title field, enter a title for the new database. The title can have a maximum of 32 characters. Note As you type a title, Designer adds a name to the File Name field. You can accept this database file name or change it. Database file names can be up to 8 characters and end with the file extension .nsf. If you plan to use the database you are creating as a template, use the file extension .ntf rather than .nsf. 4. (Optional) Click Encryption, select Locally encrypt this database using:, select an encryption type, and click OK. For information on encrypting a database, see Notes and Domino encryption in Managing Domino Databases. 5. (Optional) If you are creating a database that will be on a Domino Release 4.x server, click Size limit and select a size (in gigabytes), and click OK. 6. Select -Blank- as the template. 7. Click OK.

20 Application Development with Domino Designer

Tips for designing Web applications


When you design a database that is intended to be viewed on the Web, keep in mind that databases viewed from a Web browser may look somewhat different than they do when viewed from the Notes client. Each browser renders design elements with slight differences. Be sure to preview your database through each browser that will access it so that you can make adjustments to your design. Also, for databases that will be accessed through Web browsers, it is best to: Make sure the database is in the Domino Data directory or a subdirectory of the Data directory. Add form actions such as Create, Edit, and Save. For more information, see Actions. Hide features that arent supported on the Web. See Features to Avoid Using in Web Applications for a detailed list. Select the database property Web access: Use JavaScript when generating pages to allow you to use additional @commands and create multiple form buttons. Change from the Lotus color palette to a Web color palette to provide greater color fidelity on the Web. To change palettes, choose File Preferences - User Preferences. Check Use Web Palette on the Advanced options list of the Basics page. Set views, outline controls, action bars, and rich text fields to be displayed as applets when viewed with a browser. For more information, see the topic Domino Applets. Check the Access Control List (ACL) setting to make sure it allows appropriate access for Web users. For more information, see Setting up the ACL for a Web database. in Managing Domino Databases.

Chapter 2: Creating an Application 21

Domino Applets
When users run a Domino application from a Web browser, some Domino design elements are more effectively presented to Web users using Java instead of HTML. Domino provides Java applets for these design elements so that the interface for Web users is closer to the interface for Notes client users. You can easily enable the Java applets when you create the design element. When you consider whether to use the Java applets or HTML, keep these points in mind: The applets provide a more interactive interface. The Domino applets will require download time to the Web user. The applets use the Java Developers Kit (JDK), Release 1.0.2 to support Web users with any java-enabled Web browsers. The only fonts supported are typically Courier, Helvetica, and Times. For a complete description of how the applets work, see the description for each design element: Outline applet The outline applet lets Web users work with outlines embedded in a page or form. View applet The view applet lets Web users use many of the Domino view features, including column resizing, multiple document selection, and section collapse/expand without page regeneration. Action bar applet The Action bar applet lets users scroll and easily view and select sub-actions. Editor applet The editor applet lets Web users change the font, color, size, and style for text in rich text fields.

22 Application Development with Domino Designer

Changing database and design properties


The Properties boxes for a database and its design elements include styles, options, and other settings that affect how the database looks to users. To change these properties, you need Designer access or higher in the database access control list. To change a databases properties 1. Open or select the database. 2. Choose File - Database - Properties. 3. Change the properties on any of the tabbed pages. To change a design elements properties 1. Open the database. 2. In the Design pane, click the type of design element youre working on. 3. Open or select the design element from the Work pane. 4. Choose Design - <design element name> Properties to open the Properties box for the selected design element. 5. Change the properties on any of the tabbed pages.

Setting Use JavaScript when generating pages for a database


If your application will be accessed on the Web, youll want to select the database property Web access: Use JavaScript when generating pages so you can use additional @commands and create multiple form buttons. If you are upgrading from Release 4.5, consider the upgrade issues before deciding, because the property can cause unexpected behavior in existing actions, buttons, and hotspots. The Use JavaScript when generating pages option is on the Database Basics tab of the Database Properties box. To open the Database Properties box, open or select the database and choose File - Database - Database Properties.

Chapter 2: Creating an Application 23

Ramifications for Use JavaScript when generating pages for a database


Be aware that selecting the Web access: Use JavaScript when generating pages affects formulas and actions, buttons, and hotspots throughout the application.
If you select Use JavaScript If you dont select Use JavaScript

Documents and navigators display faster Documents and navigators display more because hotspot formulas are not slowly because the hotspot formulas are evaluated until users click each hotspot. all evaluated at the display time. Domino doesnt generate a Submit button automatically. Create a Submit button, hotspot, or action whose formula includes these commands: If there are no buttons, Domino automatically generates a Submit button at the bottom of the form. Domino only recognizes one button on a form. If there are multiple buttons on the form, @Command([FileSave]); Domino recognizes only the first button @Command([FileCloseWindow]) and converts it to a Submit button You can have multiple buttons on a form. automatically. The following commands are supported on the Web: @Command([FileCloseWindow]), @Command([FileSave]), and @Command([ViewRefreshFields]) The following commands are not supported on the Web: @Command([FileCloseWindow]), @Command([FileSave]), and @Command([ViewRefreshFields]) Domino checks the formulas before displaying pages. Actions that contain unsupported @commands or @functions will not be displayed on the Web.

Upgrade issues for Use JavaScript when generating pages for a Web database
Elements with unsupported formulas that Domino hid automatically in Release 4.5 may now display if you select the Use JavaScript property. With the property selected, Domino doesnt check any hotspot or button formulas before using JavaScript to generate the page. Web users see all buttons, actions, and hotspots even those that contain @commands and @functions that arent supported for Web applications. Revise any formulas that relied on hotspot formulas being evaluated at display time. Make sure these formulas evaluate correctly after the user clicks the hotspot, not before.

24 Application Development with Domino Designer

Replace Release 4.5 attachment fields with Embedded Element - File Upload Controls if you set the Use JavaScript property. The Use JavaScript setting disables @Command([EditInsertFileAttachment]) hotspots used to create attachment fields in Release 4.5, because the hotspot is not evaluated when the page is displayed. The Use JavaScript property can cause unexpected results because the URL generation in Release 5.0 is different than it was in Release 4.6. Check any formulas that rely on accessing a Query_String or Path_Info URL fragment. The URLs will frequently be different. For example, POST URLs that included ?CreateDocument and ?SaveDocument are no longer generated in Release 5.0. The new POST URL is a variation of ?OpenForm or ?EditDocument.

Setting database launch properties


You can set database properties that control what a user sees when the database opens. For example, you might want all users to start from an application home page or a registration page. Or you might display a main navigator that leads users to different pieces of the application. You can specify one option for an application when it runs on a workstation and another option for the application when it runs on the Web. When the database opens on the Notes client, you can display: The database as the user last viewed it The About This Database document for the database A frameset you specify A navigator you specify A navigator you specify in its own window The first attachment in the About This Database document The first doclink in the About This Database document When the database opens on a Web browser, you can display: Use the Notes launch option The About This Document document A frameset you specify A page you specify A navigator in its own window The first doclink in the About This Database document A doclink you specify The first document in a view
Chapter 2: Creating an Application 25

To set the database launch property


1. Select or open the database and choose File - Database - Properties. 2. Click the Launch tab. 3. Do one or both of the following: Choose what to display for a Notes client Choose what to display for a Web browser 4. (Optional) Choose whether to display the About This Database document when the database opens for the first time and/or when the About This Database document is modified. Setting the database property to launch the first link in the About This Database document gives users access to information in another application from a Designer application. For example, to collect spreadsheet data for use in the application, launch a link to a spreadsheet application so users immediately see the spreadsheet when they open the database. Data entered in the spreadsheet can be used to populate fields in the application. To view the About This Database document, users choose Help - About This Database or close the link or attachment. If you choose to launch a page, you will need to specify the page. Designer gives you a drop-down list of the pages that are available to choose from. If you choose to launch a doclink: 1. Copy the doclink on to the clipboard. 2. Open the Database Properties box. 3. On the Launch tab choose - On Web open launch designated doclink. 4. Click Paste doclink. To launch a Page from the Notes client 1. On the Launch tab of the Database Properties box, choose On Database Open - Open designated Navigator. 2. Select Type of Navigator: Page. 3. Enter or select the name of the Page.

26 Application Development with Domino Designer

Displaying a document preview automatically You can automatically display a preview pane that shows the contents of the highlighted document in a database view before the user opens the document. This gives users a sense of what is in a database without having to open and close each document. If you do not display the preview pane automatically, users choose View - Document Preview to access it. 1. Select or open the database you are designing and choose File Database - Properties. 2. Click the Launch tab. 3. Click the Preview Pane Default button. 4. Choose a location where the document preview pane will display. 5. Check Maximize document preview on database open to automatically display the preview pane.

Settings for multilingual applications


If you are creating an application that will have different language versions, you can select Multilingual Database on the Design tab of the Database Properties box. Once you have enabled the database as a multilingual database you can select the default language and region. This property works in conjunction with the language preference setting on users browsers. For example, if you have three versions of your database, one in English, one in French, and one in Spanish, and the users browser or Notes client preference is set to Spanish as the default language, the Domino server will serve up the Spanish version of the home page. This property is also available for individual design elements and works in the same way.

Domino Global Workbench


Domino Designer ships with the Domino Global Workbench, a fully integrated translation tool specifically designed to facilitate the translation of Designer applications into a variety of languages. If you decide to use Domino Global WorkBench, a number of design-stage tasks will make the localization process simpler. For example, you should use aliases for the names of design elements wherever you can. Use a system of standard prefixes for the aliases so that they can easily be identified as text to exclude from translation. To launch Domino Global Workbench, click the Domino Global Workbench icon. For more information see Preparing Source Databases in Domino Global WorkBench Help.

Chapter 2: Creating an Application 27

HTML tag attributes for a Domino server


The HTML tab appears on many properties boxes. If you are designing an application that will be used on the Web and are using HTML 4.0, the HTML tab on the Database Properties box lets you access core attributes, such as Cascading Style Sheet (CSS), easily. Domino incorporates the values of these attributes to the HTML that it creates at runtime. When you are using the HTML tag attributes, remember: The HTML must be ASCII characters. Do not include quotation marks when you enter the attributes in the various boxes, except for the Other box. Other needs quotation marks, as shown in the example below.

HTML tag attributes


ID: used to reference an object using JavaScript. For example, the object could be
ID = ZipCode

Class: used to specify a CSS class for an object. For example, if the objects name is ZipCode, the class could be Numeric.CSS styles are defined in the HTML Head Content event for a form or page. Style: used to apply a specific CSS styles to an object. For example, if the objects name is ZipCode, the class is Numeric, the style could be font-size:10pt, or if you have more then one value, separate them with a semi-colon, for example, font-size:10pt; color:blue. Title: used to prompt the user to enter a value for the object. For example, if the objects name is ZipCode, the class is Numeric, the style is Bold, the title could be Enter your Zip Code. The title displays differently on different browsers. Other: used for additional HTML tag attributes and must be written as pure HTML code. For example, instead of writing ZipCode in the Name/ID box, you have to write ID=ZipCode.

28 Application Development with Domino Designer

Hide-when options
Designer lets you hide many of the design elements and components of an application. If hide options are available, the hide when tab appears on the properties box for that element. To set hide-when options, select the element you want to hide and open the properties box for that element. 1. Click the Hide tab. 2. For basic options, select all situations in the Hide paragraph when document is: section in which the components dont need to be seen by users. 3. For programmer options, select Hide paragraph if formula is true and write a formula in the design pane to describe the situations in which users dont need to see the layout region. You can hide elements, including its text, graphics, and fields, in any of these situations. When users read, hide information that is useful only when users create or edit documents. When users edit, print, and copy, hide information that is useful when users read documents.
If an element is hidden Then: when: Previewed for reading Previewed for editing Opened for reading The hidden information isnt visible when users read documents in the document preview pane. The hidden information isnt visible when users work on documents in Edit mode in the document preview pane. The hidden information isnt visible when users open documents in Read mode. A layout region that cant be read cant be printed either. The hidden information isnt visible when users work on documents in Edit mode. The hidden information isnt visible on printed documents. The hidden information isnt visible when information is copied to and pasted from the Clipboard. This setting doesnt affect documents copied at the view level. A formula determines the circumstances in which information is hidden.

Opened for editing Printed Copied to the clipboard

Hide paragraph if formula is true

Chapter 2: Creating an Application 29

Enabling subscriptions
Subscriptions work in conjunction with the Headlines database. The Headlines database enables users to stay informed of current events both within their company and on the Web. The headlines database lets users subscribe to databases that are of interest to them and then receive notification when a posting meets their subscription profile. To design a database that can be subscribed to by users: The database must reside on a server that allows subscription monitoring. The Domino administrator must enable subscriptions on the server document. See Administering the Domino System for more information on enabling subscriptions at the server level. The database must enable headline monitoring. This is enabled on the Advanced tab of the Database Properties box. It is enabled by default. For more information about performance issues with headline monitoring, see Prevent headline monitoring in Managing Domino Databases. The database must contain a subscription form. You can design one yourself or copy the subscription form from the headlines.nsf database installed with the Notes client. To copy the subscription form from the headlines database to your database, see To copy and individual design element. If you are creating a subscription form from scratch, you must use a formula field. For more information, see the topic Formula fields.

Reducing database maintenance with shared resources


Each database can contain its own library of shared resources. Shared resources let you reference a resource repeatedly throughout an application, while only having to maintain in one standard place. For example, if you use your company logo in many places throughout your application and the design of your logo changes, you need only change it once, in the image resource, and the change will be implemented everywhere that image is referenced. You can create the following resources: Image resources Images resources are graphic files that can be used throughout your application. Images resources can be gif, jpeg, or bmp format. They are saved in Designer as gif or jpeg. An image resource can be used as graphics or icons on pages, forms, action buttons, outline entries, and as background images on forms, documents, pages, table cells, and action buttons.
30 Application Development with Domino Designer

Shared Fields You can define a field for use on more than one form. For example, many forms have a creation date field; you can define this field once and reuse it. When you define a field as a shared field, Designer displays the field with a dark border and adds the field name to a list of shared fields available for use in a database. For more information, see the topic Creating shared fields. Subforms A subform is a collection of fields you plan to use in more than one form. For example, you might create a corporate letterhead in a subform and then use the subform on a variety of business forms. For more information, see the topic Subforms. Script libraries A script library is a place for storing and sharing LotusScript programs and Java code. The script library contains (Option), (Declaration), Initialize, Terminate, and user scripts. All scripts in a database can share the code in a library in that database. For more information about Script Libraries, see Using script libraries in the Programming Guide. Shared Java files For large Java applets with multiple files, it is most efficient to store some of the related files as shared resources in the database. When you set up files as shared resources, all the applets can use a single copy of the file, instead of each applet storing its own copy. Then, if a file requires updating, you only need to update one file. For more information, see the topic Setting up shared applet resources. Shared Actions Use shared actions in forms or views to set up user-activated tasks. You can make shared actions available in the Actions menu or as buttons on the action bar. In particular, actions let users complete tasks when accessing Domino databases on the Web. For more information on shared actions, see Create and insert a shared action.

Creating an image resource


Create a resource library of images to use throughout your database. Although there are other methods for using images in a database, using image resources is the most efficient, because with image resources you need to maintain the image in only one location. If there are any changes to the image, changing and refreshing the source file distributes the changes wherever the image is referenced.
Chapter 2: Creating an Application 31

To Create an image resource 1. Expand Resources in the Design pane. 2. Select Image from the list of Resources. 3. Click the New Image Resource button. 4. Select gif, bmp, or jpeg in the Files of Type: list. 5. Select one or more graphic files you want to include as image resources. 6. Click Open. Designer creates an entry for each of the files you select.

Image resource properties


To access the Image Resource Properties box, select the image from the list of images and choose Resource - Resource Properties. On the Design tab of the Image Resource Properties box, select any of the following design options: Prohibit the design to be modified if the databases design is refreshed or replaced Hide the image from Web browsers or Notes clients Image resource sets There are two types of image resource sets: horizontal and vertical. A horizontal image set creates an image that seems to change based on its state. (For example, a mouse passes over an image that appears to light up. Or, an image can darken as a user clicks on it, and dim once clicked.) To create a horizontal image set 1. In your graphics program, copy and modify an image up to three times. All of the images must be the same size. The number of images corresponds to the number of states you are using. The four images map to the four states as follows:
Images across property to select 1 2 3 4 State Normal image Mouse-over image Selected image Clicked image Position of image used First position Second position Third position Fourth position

2. In a gif, bmp, or jpeg file, line up the images horizontally separated by a one-pixel space or line. 3. Create an image resource entry for image file.

32 Application Development with Domino Designer

4. On the Basics tab of the Image Resource Properties box, choose the number of images across Note The order of the states is predetermined and cannot be changed. However, if you want to take advantage of only two of the states, for example, if you want to use a different image in the normal state (the first position) only, copy the second image two or three times so that the different image is in the first position.

Using a vertical image set Use a vertical image set for icons you add to the bookmark bar. The bookmark bar can display small, medium, or large icons if the image resources for the icons are part of a vertical image set. A vertical image set includes an icon in three different sizes. (Users choose what size icons they want displayed in the bookmark bar in their User Preferences.)

To create a vertical image set, follow the steps for creating a horizontal image set but, in Step 2, line up three differently sized images vertically, with a one-pixel space between each one, and in Step 4, select how many images down you are using. In addition, use a background around the images to create a rectangle. To colorize grays If you want an image to blend with the users system colors, select the option Colorize grays on the Basics tab of the Image Resource Properties box. When enabled, the grays in an image that correspond to the Lotus
Chapter 2: Creating an Application 33

palette grays change to a corresponding color scale using the color scheme of the users operating system. This feature lets the image resources blend in with the other elements of the users system, such as dialog boxes and menu bars. Inserting an image resource 1. Open a form, document, or page. 2. Place the cursor where you want to add the image. 3. Choose Create - Image Resource. 4. Choose the type of image gif, jpeg, or All Images from the Image Type list. 5. Select the name of the image file. 6. Click OK to display the image in the form, document, or page. Tip To use the images among multiple databases, put the image into a template and inherit the resources into all the databases where theyre needed. For more information on creating templates and inheriting design, see Completing an application. Making design changes to an image resource To make design changes to a graphic used as an image resource, export the image to a graphics program. Once the changes are made, update the image resource and distribute the design changes. To export an image resource 1. Select the image you want to redesign. 2. Choose Image - Export. 3. Select the directory you want to copy the image to. 4. Click Open. To distribute design changes for an image If the image you are using changes, you can distribute those changes wherever the image appears in the database. 1. Select the image that has changed and choose Resource - Refresh. 2. Select the new image from the filing system. It doesnt matter if the name of the image has changed. 3. Click Open. Designer automatically updates the image in all of the places it is referenced in the application.

34 Application Development with Domino Designer

Designing an application for maximum accessibility for people with disabilities


When designing an application, keep in mind there are things you can do to make your application accessible to people with physical disabilities. To be accessible and meet federal accessibility guidelines, your application must be: Keyboard-accessible An application is keyboard-accessible if it can be used without a mouse or other pointing device. Screen reader-accessible An application is screen reader-accessible if vision-impaired users can access your application with screen readers. Screen reader software, in conjunction with a digital speech synthesizer, provides an auditory representation of what is on the screen or the cursor. In order to function, the screen reader software must have detailed information about the graphical user interface (GUI), so that it can translate the graphical display into speech. It must also follow good user interface design practices regarding the use of color, text, and graphics. The Notes client itself is both keyboard-accessible and screen reader-accessible. On those platforms which support it, Notes uses MS Active Accessibility (currently only available on Windows 95). However, application developers must be aware that it is possible to create an application in Designer that is not accessible. Many of the objects you create in Designer have the capacity to be made accessible. For example, images can have alternate text tag. Also, the Domino server will automatically generate accessible HTML whenever possible. There are, however, some design elements that are not accessible. Here are some important things to keep in mind when you are building your application. Use text as the primary means of communicating information. Text and rich text are accessible in almost every situation. Use the Alternate text tag on all images and applets. Both images and Java applets allow you to specify a short piece of text to be displayed with the graphical object. Normally the alternate text appears only when the object is loading or when a user has turned off image or applet loading in their browser preferences. However, alternate text is also used by screen reader software to describe the contents of an object. Specify alternate text on the Basics tab of the Picture and Java applet Properties box.

Chapter 2: Creating an Application 35

Use Action buttons that echo items in the Action menu. Screen readers cannot always provide information about action buttons. By echoing action buttons in the Action menu, you ensure accessibility in this area. To make sure that an action button is echoed on the Action menu, open the properties box for the action and select Include in Action Menu. Avoid: Using Java applets as the sole means of navigating or performing an action. Java accessibility is currently not widely supported, and a keyboard-only user cannot navigate to a Java applet in many browsers. Excessive use of embedded objects. Although these are keyboardaccessible, navigating through too many objects can be a burden for keyboard-only users. Excessive use of framesets. It is laborious for keyboard-only users to navigate through framesets. The fewer frames used in an application, the easier it will be for a keyboard user to navigate. Using color and graphics as the sole means of communicating meaning in your application. To test if your application is usable for color-blind users, set your display to monochrome and check all graphics for legibility. Very small text. Some operating systems support a large font user preference, but this preference is not respected by all objects in an application. Avoid using text smaller than 10 point Helvetica. If accessibility is a major priority for your application, you may want to consider creating an alternate interface for your application using only text and non-embedded controls. For more information about accessibility, visit the IBM Special Needs Web site at http://www.austin.ibm.com/sns/ or the W3 Web Accessibility Initiative (WAI) site at http://www.w3.org/WAI.

36 Application Development with Domino Designer

Previewing your design work


In order for you to be able to test your application to see how it looks and behaves from the Notes client and the Web, you can preview your work in supported browsers. When you start up your system, Designer searches for the following browsers: Internet Explorer Netscape For each supported browser Designer finds, it adds an icon to the tool bar in the upper right corner of the Design pane. If you have both Netscape version 3.x and 4.x both icons are added. There are also icons for previewing through the Notes Browser and previewing in Notes. Previewing design work in the Notes Browser is not equivalent to choosing to Preview in Notes. Previewing work in the Notes Browser serves the application through the Domino server, while Previewing in Notes serves the application directly to the Notes client. Clicking a browser icon previews the current design element that is, the page, form, or navigator you are designing in the associated browser. You can also preview elements from the Design list. For example, you do not need to open up a form to preview it; you can select it in the list of forms and click one of the preview icons. To preview in Notes or in the default Web browser using the menu 1. Open the design element you want to preview or select it from the Design list. 2. Make design changes if necessary. 3. Choose Design - Preview in Notes or Preview in Web browser <Web browser>. You will be prompted to save any changes. If you do not save your changes, Designer will preview your work without the changes. To shut down the HTTP process that runs the Web Browser preview without exiting Notes, choose File - Tools - Stop Local Web Preview Process.

Chapter 2: Creating an Application 37

To preview in Notes or in the default Web browser using the preview icons 1. Open the design element you want to preview or select it from the Design list. 2. Make design changes if necessary. 3. Click the icon on the Menu bar that represents the browser in which you want to preview. You will be prompted to save any changes. If you do not save your changes, Designer will preview your work without the changes.
Notes client Domino Internet Explorer Netscape version 3.x Netscape version 4.x

To shut down the HTTP process that runs the Web Browser preview without exiting Notes, choose File - Tools - Stop Local Web Preview Process.

Requirements for previewing your design work on the Web


A Windows 95, Windows 98, or NT workstation. You must modify the applications access control list. The Web preview process uses the access assigned to -Default- or, if available, an entry called Anonymous. One of those entries needs Reader access to let you preview pages, framesets, documents, navigators, and views. One of those entries needs Author access with create document permission to let you preview forms. The element to be previewed must reside in a database under the Notes data directory on the local machine or on a server running the HTTP task. The element to be previewed must not be marked as hidden from Web browsers. Your browser(s) must be set up to override proxy settings (described below). To set up a default browser for previewing To set up previewing, you must override the proxy settings so the preview process can find the databases both on your local machine and on any servers that have databases you need to preview.
38 Application Development with Domino Designer

1. In Designer, choose File - Preferences - Location Preferences. 2. Next to Proxy, click the Advanced icon. 3. Next to No proxy for these domains, add these case-sensitive entries:
localhost <Domino server name>

4. Click OK. 5. Close and save the Location document. To override proxy settings for additional browsers If you use alternate browsers, you must set them up for previewing. See the Help for your browsers for more specific information on proxy settings. 1. Open each browser, and then open its Proxy settings page. 2. Specify these case-sensitive entries:
localhost <Domino server name>

3. Click OK.

Chapter 2: Creating an Application 39

Chapter 3 Designing Outlines


This chapter introduces outlines, shows you how to create and format an outline, and shows you how to embed an outline on a form or page to use it as a navigational structure for your application.

Outlines
Outlines, like imagemaps and navigators, are tools that let you provide navigation in your application. All databases come with a default navigation structure called the folder pane (also referred to as the navigation pane). The folder pane, by default, displays a list of shared views and shared folders. In the Notes client it appears in the left pane, and in a Web browser, the folder pane displays at the top left of the browser window. When users click on the view or folder they want to access, that view or folder is displayed in the right pane. If you want create a custom navigation structure for your application, create an outline. In addition to jumps to all of the views and folders in your database, you can include actions or links to other elements. You can create an outline that navigates through your entire application or site, or through part of it. You can also use outlines to help you plan your application. To do so, you create an outline that represents the skeleton of your application, in which each outline entry represents a design element or component of the application. Once you create an outline, you embed it on a page or form. This displays it to users, who use it as a site map or navigational structure. Users can click on the outline entries to take them where you want them to go. The process of creating a navigation structure using an outline involves the following steps: 1. Create a new blank or default outline. 2. Create outline entries for jumps or actions you want to present to the user. 3. Embed your outline on a form or page or in a rich text field of a document.
41

4. Format the display of the embedded outline. 5. (Optional) Include embedded outline in a frameset. Some important features of the Outline include: You can completely customize an outline, reordering how items appear in the folder pane as well as including jumps to elements outside of your application. You can control how the outline appears to users by changing text and button styles and adding icons from your databases shared resources. Outline entries are fully programmable. You can add logic that controls how outline entries are rendered by the Notes client or Web browser. By combining the outline with Framesets, your application can include multiple outlines that launch links in target frames.

Creating an outline
You can create an outline from scratch or generate a default outline. If you are using the outline to help you plan your application, you can create the outline entries prior to designing the actual design elements. Begin by creating a new outline and then adding entries for each element you plan to include in your navigator or site map.You can include outline entries for any element that will be part of your application or site, such as jumps to pages, documents, views, folders, Web pages, or other Domino databases. Outline entries represent each piece or planned piece of your application or navigation structure. Outline entries can also be clickable actions or can be top-level categories that organize other entries. You can also choose what icons display with the entry. You can organize your application into units and create multiple outlines to represent the different portions of your application. If you have already created all of your design elements or are working with a database created from a template, you can begin by creating a default outline and customizing it. To create a new outline from scratch 1. Click Outlines in the Design pane. 2. Click New Outline. 3. Add outline entries for each design element, action, or link you want to include in the outline.

42 Application Development with Domino Designer

To create a default outline The default outline creates outline entries for all the views and folders in the database. In addition, the default outline contains placeholders called Other views, Other folders, Other private views, and Other private folders. Click Generate Default Outline. To add a new outline entry: 1. Click New Entry. 2. In the Outline Entry Properties box, enter the label you want appear in the outline, for example, Home Page or Main View. 3. Enter a type for the element in the Content field. If you are creating a jump to a named element that does not yet exist, Designer will display a prompt letting you know that you will need to create the element later. Jump to: A URL (enter entire URL including protocol, for example http://www.lotus.com) A link - such as to an anchor, document, view, or database link A named element - such as a Page, Form, or View Perform an action - such as open or create a document. To enter an action, click the @ button, and enter a formula. None (use this to create a top-level category for nesting entries). 4. (Optional) Enter an alias for the outline entry. 5. (Optional) Enter the target frame for the jump or action. If you have not yet created your frameset, you can either enter the name you are planning to use in your frameset or you can add this entry later, after you have created your frameset. Note You can cut and paste outline entries from other outlines. Once you have created outline entries for the elements that you are including in your application, you can reorder the elements or create a hierarchy between them.

Chapter 3: Designing Outlines 43

To reorder elements in an outline Create the order for the outline entries as you want them to appear to the user. You can reorder the elements after you create them. To reorder the elements in an outline: Select one or more outline entries in the Design pane and drag to move them up or down in the list. To create a hierarchy between elements Outline elements can have a hierarchy, that is, there can be top-level entries and sub-level entries.

This is especially useful, for example, if you would like to create nested outline entries. To create a hierarchy between elements do one of the following: Select one or more outline entries and click the Indent Entry button (or press the TAB key) to indent the element one tab stop to the right. Select one or more outline entries and click the Outdent Entry button (or press SHIFT-TAB) to outdent the elements one tab stop to the left.

44 Application Development with Domino Designer

To delete an outline entry 1. Select the outline entry that you want to delete. 2. Press DEL or choose Edit - Clear.

Embedding an outline
To use an outline as a navigational device, it must be embedded on a form, page, or rich text field of a document. Whether you choose to embed your outline on a form, page, or document will depend on how you want to use it. You can embed the outline on a form so that each document created from that form includes the embedded outline. The outline then presents an easy way for users to navigate to other views, create a new document, move to the next document, and so on. For example, in a Discussion database, you can embed the outline on the Main Topic form. When an user creates a document with that form, the outline appears on the document. Embed the outline on a Page if you want to use the outline as part of a Frameset or as part of your home page. Embed the outline on multiple pages if you need to have several occurrences of the same outline with different styles (for example, one outline with only text, another with graphical buttons). If you want several navigational structures in one application you can do two things. You can create one outline and embed it several times on different pages, or you can create several different outlines and embed each on different pages. Embedding the outline on a page 1. Click Outlines in the Design pane. 2. Open the outline you wish to embed. 3. Click Use Outline on the action bar at the top of the Design pane. The embedded outline appears on a new page with the default style applied to it. 4. Choose File - Save. You will be prompted to enter a name for the Page which the outline is now embedded on. Embedding the outline on a form, page, or document 1. Open or create the form, page, or document you want to embed the outline on. 2. Position the cursor where you want the outline to appear. In a document you must be in a rich text field. 3. Choose Create - Embedded Element - Outline. Once you have embedded your outline, you can format it.

Chapter 3: Designing Outlines 45

Outline, outline entry, and embedded outline properties


There are three sets of properties associated with outlines: Outline properties Outline entry properties Gives the outline a name and alias Makes the outline available to public access users Assigns a label and alias to the outline entry Selects what the entry will do: Jump to a URL, link, or named element, perform an action, or nothing Selects the link or enters a formula Enters the target frame for the action or link Selects the image Selects Refuse selection Selects hide options for the entry Formats the embedded outlines look and structure

Embedded outline properties

Selected outline properties


Making the outline available to public access users This must be enabled for the outline to be available to public access users users with no access to the database, but who have the privilege to read/write public documents. (Public access users will be able to open the database to views enabled for public access and to read/write documents enabled for public access.) If the designer wants the public access user to be able to use the outline for navigation, the outline must be enabled for public access users. The page and frameset in which the outline appears must also be enabled for public access users. For more information about public access, see Creating pages, forms, outlines, views, and agents for public access.

Selected outline entry properties


To add an image to the entry You can display an image with any outline entry. By default, outline entries for views will display the view icon, and outline entries for folders will display the folder icon. You can display these icons, choose one of your own, or choose no graphic. In order to use a graphic as an outlines icon it must be added to the databases shared image resources.

46 Application Development with Domino Designer

To add an image to appear next to your entry 1. Select an outline entry and choose Design - Outline Entry Properties. 2. On the Outline Entry Info tab click the folder icon in the Image section and select the shared image resource for your graphic. 3. (Optional) Click the @ button to use a formula to control the display of the image. 4. (Optional) If you do not want to display an icon with the outline entry, select Do not display an image. Does not keep selection focus After a user clicks on the entry, the entry will not remain selected. The previously selected entry will retain the focus. To hide an entry You may want certain entries to show up only under certain circumstances. For example, you can program an entry to be hidden when viewed with a Web browser. To hide outline entries: 1. In the Outline Entry Properties box, click the Entry Hide When tab 2. Select an option for hiding the entry or enter a formula in the formula box.

Selected embedded outline properties


You can control the display and behavior of the embedded outline using the Embedded Outline properties box. There are two different style properties that control how the embedded outline appears to the user: Type and Title styles. The first, Type, determines whether the outline shows the hierarchy of the outline entries. The hierarchy is set up when you outdent and indent outline entries. If you select Tree style for type, then all of the outline entries that have indented entries below them will show up as expandable sections. You can choose to have green triangles (or twisties) display next to expandable outline entries, or users can click on the top-level entry to expand it. In a Tree style outline, all top-level entries show at all times. Users expand and collapse entries as necessary.

Chapter 3: Designing Outlines 47

Tree style outline with twisties turned on:

Tree style with simple title:

A Flat style outline displays one level of entries at a time. Initially, all top-level entries display. When you click an entry, if it is expandable, the sub-level entries associated with that entry will display. If it is not expandable, it will jump to whatever link or action is associated with it. If you want users to be able to navigate back up the outline, select Simple for the title style. The title will continue to display allowing users to click on it to get back to the previous level. If you choose Hide for the title style you must provide a button or action if you want users to be able to return to the top-level of the outline.

48 Application Development with Domino Designer

Initial display for flat style outline:

After clicking Phone Book entry:

To change display attributes: 1. Open the form or page that the outline is embedded on. 2. Select the outline. 3. Choose Element - Outline Properties to display the Embedded Outline properties box. In the Embedded Outline properties box you can set the overall display of the embedded outline. On the Info tab you can set: Type style - Tree or Flat. This setting allows you to decide whether to show the hierarchy of the Outline or not. Tree style shows all of the outline entries in the hierarchy, while Flat shows only one level at a time. Use the Flat style selection in conjunction with the Title style setting. If you choose Flat style, you have the option of displaying the outline vertically or horizontally. Display horizontally displays entries to fit the window across instead of down.

Chapter 3: Designing Outlines 49

Title style - Hide or Simple. These settings work in conjunction with the Type: Flat Style setting. In a Flat style outline, Simple style lets users navigate back up to prior levels by displaying the parent of the current level in a flat outline. Hide style does not display any hierarchy, so once users go down a level in the outline they cannot navigate back up. Root entry - Defining a root entry will show the children of the specified entry only. This can be used as a way to restrict users access to elements in your site or database. Specify a root by using the alias of the parent entry. For example, if a parent entry has an alias of Main, enter Main in the Root entry box and only that entrys children will display in the outline initially. If the specified entry does not have any children, then nothing will display in the outline. If you want to give users a way to navigate back up the hierarchy from the root entrys children, enable Simple as the Title style for either a Tree or Flat outline. If you want to limit users access to those children entries only, set the root, and dont enable a Title style. On the Font tab, select either Top-level font or Sub-level font to format the font of the outline entries. If Title style is set to Simple, select the Title Font. You can also select font colors for: Normal state of entries On Select (when the entry is selected) On Mouse (when the mouse passes over the entry) For each of the areas on the embedded outline, you can specify color or image backgrounds on the Background tab. You can set mouse-over and selection colors. Images can be tiled in various ways, such as top to bottom, or left to right, or positioned under the text, for button effects. Images must be shared image resources for the database. On the Layout tab you can set the positioning for the title-level (if Simple title is enabled), top-level, or the subsequent levels of: The entire outline entry Height - height of each entry. (This setting represents the width of each entry in a flat horizontal outline.) Vertical offset - aligns the outline entries relative to the top edge of the embedded outline. If you want to customize the spacing between outline entries, use this setting. Horizontal offset - aligns the outline entry relative to left edge of the embedded outline, for title or top-level entries. Sub-level offset is relative to parent entrys left edge.

50 Application Development with Domino Designer

The label text of the outline entry Alignment - within the outline entry. Vertical offset - relative to the embedded outline, depending on alignment; ignored for a middle vertical alignment. Horizontal offset - relative to the embedded outline, depending on alignment; ignored for a center horizontal alignment. The outline entry image Alignment - within the outline entry. Vertical offset - relative to the embedded outline, depending on alignment; ignored for a middle vertical alignment. Horizontal offset - relative to the embedded outline, depending on alignment; ignored for a center horizontal alignment.

Using the outline applet


When you are designing a Web application, you have two options for defining how an embedded outline displays in a browser: Define the embedded outline as HTML. This is the default behavior. Define the embedded outline as an applet. The outline applet lets Web users work with outlines embedded in a page or form. With the outline applet, Web browser users can: See mouse-over distinctions for items in the outline, including change of color to indicate a selected item See background images To enable the outline applet 1. Embed an outline in a page or form, or select an existing embedded outline. 2. Choose Element - Outline Properties. 3. On the Info tab select Web access Using Java applet.

Chapter 3: Designing Outlines 51

Displaying the outline in a Frameset


Once you have the outline formatted you can insert it into a Frameset. 1. Select Frameset from the list of design elements for the database. 2. Open an existing Frameset that you want the outline to display in, or create a new Frameset by clicking the New Frameset Button on the action bar. 3. Right-click on the Frame you want the outline to appear in and select the Frame properties box. 4. For the Content Type select Named Element. 5. Select Page or Form. 6. Enter the Value by either clicking on the Folder icon and selecting it from the list box or typing in the name of the page or form containing the outline you want to display. 7. (Optional) Enter the name of the target frame the links should appear in when a user clicks on an outline entry. For more information, see Specifying a target frame. For more information, see Designing Framesets.

52 Application Development with Domino Designer

Chapter 4 Designing Pages


This chapter describes designing pages for Web and Notes applications. All procedures described in the chapter for adding components to a page apply to forms as well as pages.

Pages
A page is a database design element that displays information. Pages can be used anywhere in your application where you have text, graphics, or an embedded control, such as an outline, to present to the user. A page or form can contain the following: Text Use text anywhere on a page or form and apply text attributes, such as color, size, and font styles to the text. For complete information on creating and formatting text, see Notes 5 Client Help. Add horizontal rules to separate different parts of a page or form, or to make a page or form more interesting visually. Use tables to summarize information, align text and graphics in rows and columns, or position elements on a page or form. For information on creating programmable tables, see the topic Creating a programmable tables. For all other information on creating and formatting tables, see Notes 5 Client Help. A section is a collapsible and expandable area that can include objects, text, and graphics. An access-controlled section allows only certain users to read the section. Add links to take users to other pages, views, databases, or a URL when they click on text or a graphic. Place a graphic anywhere on a page or form. Use graphics to add color to a page or form or to create imagemaps.
continued

Horizontal rules Tables

Sections

Links Graphics

53

Imagemaps

An imagemap is a graphic you enhance with programmable hotspots. Hotspots, in the form of pop-up text, actions, links, and formulas, perform an action when clicked by a user. Use Imagemaps as navigational structures in an application. Attach files to a page or form so users can detach or launch files locally. Actions automate tasks for the user. Add actions to the menu in a Notes client, or through buttons or hotspots on a page or form. For more information, see Automation in applications. Use Java applets to include small programs, such as an animated logo or a self-contained application, in a page or form. For more information about including Java applets on a page or form, see Including Java Applets in Applications. Embed the following elements in a page or form: a view, folder pane, navigator, outline, or date picker. Use these elements alone or combine them to control how users navigate through your application. If you have existing HTML or you prefer using HTML to using the formatting tools Designer offers, you can import, paste, or you can write your own HTML on a page or form. Designer supports object linking and embedding (OLE) as well as custom controls, sometimes called OCX controls. Including a linked or embedded object on a page or form lets you use a page or form as a gateway to another application. For example, an Employee Information page or form can include an OLE object that links to a Word Pro file where the employee annual performance reviews are stored. Notes/FX 2.0 fields create a two-way exchange between Notes and a supporting application by allowing field data to be shared and updated from either application. Lotus Components are examples of controls that let you include other Lotus products such as a spreadsheet or chart in a form. For information on including OLE objects and custom controls on a form, see Designing applications that share information.

Attachments Actions

Applets

Embedded elements

HTML

OLE objects and custom controls

54 Application Development with Domino Designer

How pages relate to forms and document


Pages and forms both display information to users. Forms let you collect information as well. Fields, subforms, layout regions, and some embedded controls can only be used on forms. A page is best suited for displaying information, while a form is more suitable for gathering information.

Creating a page
To create a page 1. Click Pages in the Design pane. 2. Click the New Page button. 3. Create the contents for the page, using elements such as text and graphics. 4. Choose Design - Page Properties to assign a name and set other page properties, such as the target frame in which the page should display. To delete a page 1. Click Pages in the Design pane. 2. Select the page you want to delete. 3. Press DEL or choose Edit - Clear. 4. Click Yes to confirm.

Displaying a page
Pages do not display in views. You can display pages to the user by: Designating the page to be part of a frameset. For more information on Framesets, see Designing Framesets. Creating a link to the page from another design element such as a form, an outline, or another page. For more information on creating links, see Adding links to a page. Creating an action that opens the page. For more information on creating actions, see Actions. Creating an outline entry that opens the page. For more information on creating outline entries, see Outlines. Setting the database launch property to launch the page when the database is opened. For more information on the database launch property, see Setting database launch properties.

Chapter 4: Designing Pages 55

Creating a home page for an application


A home page gives users a logical entry point to and a summary of the information in an application. Not all visitors need to stop by the front desk, but its important to provide a home page for those who need it. Provide links to the home page from other places within the site, so visitors who enter through the back door can find their way around too. A home page should contain the following elements in a pleasing mix of graphics and text: A brief description of the company, product, service, or site Links that navigate to other parts of a site Information for new visitors Information for frequent visitors who need to know what is new A way to search for information If necessary, a way to register on the site to participate in restricted areas Create a page with links to other pages, views, documents, or navigators in the same database or other related databases at the site. You should take security issues into account when you decide whether to store the home page in its own database or in a database used for other purposes, such as discussions, user registration, or product information. You generally provide fairly open access to a home page and limit access to other parts of a site. For more information about security, see Security in an application. To set the home page to launch automatically, choose File - Database Properties, click the Launch tab, and select the page you want to launch for Notes clients and for Web clients. For more information, see Setting database launch properties. Specifying a page as a Web sites home page in the server document A server administrator can specify a page as a Web sites home page in the server document for the server. Contact your server administrator for more information.

56 Application Development with Domino Designer

Styling text for the Web


For Web applications, Domino automatically converts text styles to HTML tags when there is a corresponding HTML equivalent. This includes bullets, numbers, alignment (except Full Justification and No Wrap), spacing, and named styles. Certain types of formatting such as indents, interline spacing, and tabs do not appear when viewed from a Web browser because HTML has no corresponding format. Be aware that different browsers may display tags differently and that not all browsers support the HTML tags that Domino generates. Fonts If the fonts used are not the system defaults for example, in Windows, Default Sans Serif and Default Serif Domino converts font instructions to the HTML <FONT> tag and FACE= attribute to approximate the original font choice. Text may look different to a Web user than it does to a Notes user because the browser determines which fonts to use. Size Domino maps the text size you select in Designer to an HTML text size. The following table lists the text size in Notes Designer and the corresponding HTML size.
Text size less than or equal to 7 9 11 13 17 23 greater than 23 Maps to HTML Size 1 2 3 (this is the default size) 4 5 6 7

Note that Domino does not map font sizes to HTML heading tags (H1, H2, and so on). Preserving spaces To align a column of numbers or preserve or insert spaces, use the default monospaced font. On a Windows system, the default monospaced font is Courier. Domino converts the default monospaced font to a monospaced font on the Web and preserves any spaces you enter. Text colors Web users see the same approximate text colors as Notes users, but the colors may not match exactly.
Chapter 4: Designing Pages 57

Creating computed text


You can use computed text to generate dynamic text based on formula results. 1. Move the cursor to where you want the computed text to appear. 2. Choose Create - Computed Text. 3. In the Programmers pane, click the Objects tab of the Info List and select - Computed Text - Value. 4. Write a formula whose value displays the text you want to show in the page. Example: Computed text To personalize the message a user sees on a page or form, create computed text that displays the users name. On the page or form enter the text:
Welcome <computed text>.

For the Computed text value (located on the Object tab of the Info List) enter the formula:
@Name([CN];@UserName)

If the users name is Sara Ryan/Acme, when she opens the page or form she will see: Welcome Sara Ryan. Note Domino publishes a <span> tag around the computed text for access via JavaScript.

Changing all text styles


There may be times when you want to change the text style of all the text on a page or form. For example, you might want to customize the mail template to display all text in a different font type or size. 1. Open the page or form. 2. Choose Edit - Select All. 3. Choose Text - Text Properties and choose style options. 4. Save and close the page or form.

58 Application Development with Domino Designer

Creating and formatting horizontal rules


To separate different parts of a page or form, or to make the document more interesting visually, add horizontal rules. You can set width, height, and color (including gradient color) for horizontal rules. To create a horizontal rule 1. Move the cursor to where you want to enter the horizontal rule. 2. Choose Create - Horizontal Rule. To change the style of a horizontal rule 1. Select the horizontal rule; choose Horizontal Rule - Horizontal Rule Properties. 2. Click the Horizontal Rule Info tab. On the Info tab you can: Change the width and height. To change the width and height in inches, choose Absolute. To change the width and height as a relative percent of the window, choose Relative (%). Select a solid color. You can select a color from the palette or customize colors by using the color wheel button in the top right corner of the Color box. To set the color of your horizontal rule to your systems color scheme, click the Color box menu and click the System button. To select a solid color, select a color and click the solid rectangle. Select a gradient color. A gradient color is a color that blends and fades into the other original color within a horizontal rule. Gradient color is not supported on the Web. To select a gradient color, select the first color, click the shaded rectangle and select the to color. Make a horizontal rule transparent. Click the Color box menu and click the transparent button. To undo transparency, click the Color box menu and click the undo transparent button. Select No 3D shading.

Chapter 4: Designing Pages 59

Creating programmable tables


Programmable tables let you create a table that displays one row at a time, based on an action or field formula. Programmable tables start with a tabbed table, much like the Properties boxes in Designer. One tab, or row, of the table is visible at a time to the user. With regular tabbed tables, the user clicks the tabs at the top of the table to switch which row displays. With programmable tables, the user selects which row appears based on clicking on an action, a link, or an outline entry. When you write the formula to control what row displays, include a field which is the name of the table proceeded by $ (a dollar sign). Also keep in mind when you are writing your formula, that field names are case-sensitive: $table is a different field name than $Table. For example, on your companys home page, you could put a programmable table that displays different information about your company depending on what your site visitors want to see. If they click Location Information they would see the row of the table that gives them the location of your company. If they click Company History they see the row of the table that describes your companys history. Note When you are designing programmable tables on a form, you have the option of using a field on the form to control the table. You can use a choice list field that refreshes on change or computed field. To create a programmable table 1. Move the cursor to where you want the table to appear. 2. Choose Create - Table. 3. Click the programmable table button. 4. Select the number of rows and columns you want in the table. Tabs are used to display rows on the table. All columns in a row will appear when that row is displayed. 5. On the Table Programming tab of the Tables Properties box: Enter a Name/ID for the table. For each row in the table, click on the tab for the row. Then, enter a name for the row in the Row Tags field of the properties box. 6. Set the display options for the table. For information about formatting tables, see Notes 5 Client Help. 7. Enter text, graphics, or objects in the table. 8. Create links, actions, or an outline that will set the fields for the table and control what displays.

60 Application Development with Domino Designer

Example: Creating Hotspots to control a programmable table 1. Create a two-row, two-column, programmable table on a page. Name the table CompanyInfo. Name the first row a and the second row b. 2. Enter text and graphics in each row and column of the table. 3. Enter a line of text on the page (below the table) that is related to what users will see when that row of the table is displayed. Enter a line for each row of the table. For example, if you have a two-row table one row has the company location and the other has the company history enter two lines of text: Our company locations Our company history 4. Select the text for the first line and choose Create - Hotspot Action Hotspot. 5. Click the Hotspot Click event in the Objects tab of the Info list in the Programmers pane. 6. Enter a formula in the Script area of the Programmers pane that sets the field $CompanyInfo to the name of the row of the table you want to display.
FIELD $CompanyInfo:= "a"; @Command([RefreshHideFormulas])

7. Select the second line of text and create a hotspot with the formula:
FIELD $CompanyInfo:= "b"; @Command([RefreshHideFormulas])

When users clicks on the first hotspot they will see the text and graphics in the first row of the table only. When they click on the second hotspot they will see the text and graphics in the second row of the table only. For more information about writing formulas, see the Programming Guide. For more information on creating basic, tabbed, or animated tables, see Notes 5 Client Help.

Creating sections
Use sections to group and organize elements on a page or form. Sections work well to present large amounts of information in an uncluttered way. For example, if you have two different procedures on a page, and users will only need to see one, you can put them into a collapsible section so that the users can expand only the section that they need.

Chapter 4: Designing Pages 61

To create a section
1. Open the page or form. 2. Highlight the text, graphics, and other elements to include in the section. 3. Choose Create - Section.

To format a section
1. Select the section and choose Section - Section Properties. 2. On the Section Title and Border tab you can: Enter a title for the section. Titles can be either text or a formula. Use text if the title should be the same all the time. Use a formula if you want the title to appear differently under different conditions. Select the border style. The border appears around the section. Select a border color. 3. On the Expand/Collapse tab: Select options for showing the section expanded or collapsed depending on whether a document is being previewed, opened for reading, opened for editing, or printed. Select Hide title when expanded if users dont need to see the section title when the fields are displayed.

To delete a section
Select the section and choose Section - Remove Section.

Creating links
You can create links that let users navigate to other parts of an application or to external sites on the Web. When users click on the text or graphic that is serving as a link, they jump to the element that you have linked to. You can set how the link displays to users in the properties box. You can use a different color text, or a hotspot around a graphic that shows up on mouse over. Domino converts these links to Hypertext links on the Web.

To create a link to a design element


To link to a design element, create a named element link. Named elements are: Pages Forms
62 Application Development with Domino Designer

Framesets Views Folders Navigators When you link to a named element, the link references the elements name. Any change in the name of the element will break the link. Whenever possible, create aliases for design elements. If the design element has an alias, the link will be maintained as long as the alias does not change. There are two ways to link to a named element. You can copy and paste, or you can use the link properties box. To copy and paste a link 1. Select the design element you want to link to. 2. Choose Edit - Copy as Link - Named Element. 3. Select the text or graphic that will serve as the link and choose Create Hotspot - Link Hotspot. 4. Click the Paste icon on the Properties box. 5. (Optional) Enter a target frame for the link. 6. (Optional) Select Show border around hotspot. (Not supported on the Web.) To create a link using the properties box 1. Select the text or graphic that you want to serve as the link. 2. Choose create Hotspot - Link Hotspot. 3. On the Hotspot Info tab of the Hotspot Resource Link Properties box, select Named Element as the type of link. 4. Select the type of Named element you want to link to and do one of the following: Enter the name of the element Click the folder icon to browse Click the @ icon to enter a formula that resolves to a link 5. (Optional) Enter a target frame for the link. 6. (Optional) Select Show border around hotspot. (Not supported on the Web.)

Chapter 4: Designing Pages 63

To create a link to a document, view, anchor, or database


These links are more stable than traditional HTML links because they do not reference file names; rather, they reference the unique internal ID of the element. If the name of the linked item changes, the link remains valid. 1. Open or select the element you want to link to. For document, view, or anchor links, open or select from the Notes client. 2. Choose Edit - Copy as Link - <type of link>. 3. Select the text or graphic that will serve as the link and choose Create Hotspot - Link Hotspot. 4. On the Hotspot Info tab of the Hotspot Resource Link Properties box, select Link for the type. 5. Click the Paste icon on the Properties box. 6. (Optional) Enter a target frame for the link. 7. (Optional) Select Show border around hotspot. (Not supported on the Web.)

Linking to a URL
Use a URL link to create a link based on a URL name. Since this type of link is based on a hard-coded URL name, any changes to the URL break the link. To create a URL link 1. Select the text or graphic that you want to use as the URL link. 2. Choose create Hotspot - Link Hotspot. 3. On the Hotspot Info tab of the Hotspot Resource Link Properties box, select URL as the type of link. 4. Enter a full URL (including protocol) for the value. 5. (Optional) Enter a target frame for the link. 6. (Optional) Select Show border around hotspot. (Not supported on the Web.)

Adding graphics
A page or form that contains a graphic is visually appealing but takes more time to display and print. You can paste or import graphics into pages, as you can into documents, forms, views, and navigators. Designer stores graphics in Graphics Interchange Format (GIF) and Joint Photographic Experts Group (JPEG) in their native formats. Therefore, these are the best

64 Application Development with Domino Designer

choices for graphic fidelity. Designer stores other types of graphics in a platform-independent 256-color format that is similar to GIF89a format. (GIFs are 256-color images.) Graphics can be: Stand-alone graphics that add aesthetics or focus to a page or form Background graphics Imagemaps navigation structures composed of graphics that contain links.

Preparing graphics
Your goal, when preparing a graphic, is to have it look as much as possible like the graphic you created in your drawing program. How graphics look depends on the users viewer, operating system, and color mode. Viewer Notes client or a Web browser Depending on your audience, you should use either the Lotus color palette or the Web color palette. If your audience is only Notes users, use either the Lotus color palette or the Web color palette. If your audience is only Web users, use the Web color palette. If your audience is both Notes and Web users, use black and white or very simply colored graphics, or use the Web color palette. Operating system Macintosh, Windows NT, Windows 95/98, OS/2, or UNIX Always reduce graphics in formats other than gif or jpeg to 256 or fewer colors. Although doing this may reduce the quality of high-resolution graphics, it ensures a more reliable color display across platforms. Color mode 16-color mode, 256-color mode, or High/True/24-bit color mode. If all users have machines that display in true color mode, reducing the colors to 256 or fewer is all you need to do to prepare a graphic. If users have machines running in 256-color mode, use a color palette to map colors in the graphic to a table of predefined colors.

Chapter 4: Designing Pages 65

Changing the color palette If you are designing applications for users to access on the Web, you can change from the Lotus color palette to a Web color palette while designing to provide greater color fidelity. To change palettes: Choose File - Preferences - Notes Preferences. Check Use Web Palette on the Advanced options list of the Basics tab. If this option is unchecked, Designer uses the Lotus color palette. Note When Web users open a database, Domino converts non-gif and non-jpeg graphics to gif or jpeg formats. The system administrator specifies the format in the Image conversion format field, which is part of the HTTP Server section of the Server document. For more information, see Administering the Domino System.

To add graphics to a page or form


There are four ways to add a graphic: Copy and paste Import a graphics file Create a picture Insert a shared resource To copy and paste a graphic 1. Copy a graphic to the clipboard. 2. Open the page or form and move the cursor to where you want to place the graphic. 3. Choose Edit - Paste. To import a bmp (bitmap), jpeg, gif, pcx image, or tiff 5.0 bitmap Because Web browsers support gif and jpeg formats directly, many developers find it easier to design graphics using these formats. 1. Move the cursor to where you want to place the graphic. 2. Choose File - Import. 3. Choose the graphic file to import and click Import. To create a picture 1. Move the cursor to where you want to place the graphic. 2. Choose Create - Picture 3. Choose a graphic to import and click Import.

66 Application Development with Domino Designer

To insert a shared image 1. Move the cursor to where you want to place the graphic. 2. Choose Create - Image Resource. 3. Choose the type of image gif, jpeg, or All Images from the Image Type list. 4. Select the name of the image file. 5. Click OK. Changing the display properties of the graphic Once you have added the graphic you can change the display properties using the properties box. Keep in mind that Domino passes the size and scaling information for graphics to the browser. If the browser supports scaling, the graphic has the same size and scale as it does in Notes; otherwise, the graphic appears in its original size, regardless of how you size it.

To resize a graphic
1. Select the graphic. 2. Choose Picture - Picture Properties. 3. Do one of the following: Drag the box in the graphics lower right corner In the Scaling field of the properties box, enter a value for the width and height To return a graphic to its original size 1. Select the graphic. 2. Choose Picture - Picture Properties. 3. On the Picture Info tab, click Reset. To set the text wrap properties for the graphic There are several alignment and text wrap properties you can set in the Picture Properties box. Alignment options indicate how the picture lines up with text on either side of it. By default, Designer aligns a picture with the bottom of the text around it. To wrap text around the picture, choose either Wrap, float image left or Wrap, float image right. 1. Select the graphic. 2. Choose Picture - Properties. 3. Choose an option for wrapping the text around the graphic.

Chapter 4: Designing Pages 67

To add alternate text for the Web You can make your application accessible to people with physical disabilities. Many of these users access applications with screen readers. Screen reader software, in conjunction with a digital speech synthesizer, provides an aural representation of what is on the screen or the cursor. In order to function, the screen reader software must have detailed information about graphics, so that it can translate the graphical display into speech. You can provide this information by making sure you include alternate text for all the graphics in your application. 1. Select the graphic. 2. Choose Picture - Picture Properties. 3. Click the Picture Info tab. 4. Enter text in the Alternate text box. 5. (Optional) Enter a caption and a caption display option.

Adding a background color or graphic


You can paste or import a bmp (bitmap), jpeg, gif, pcx image, or tiff 5.0 bitmap graphic file as a background for a page or form. If the graphic is the same size as the page or form, it appears once; smaller graphics tile to fill the background. All page or form elements appear in front of background. In addition, you can add a background color to enhance a page or form. You might want to use a standard color for a particular type of page or form, for example, white for a request page. To have the background show through part of an image, create a transparent gif file with an image editor or utility and then import the image. Both Notes and Web users see transparent background images. To choose a background color 1. Open the page or form. 2. Choose Design - <Design element > - Properties and click the Background tab. 3. Select a different background color. To paste a bitmap as a background 1. Copy to the clipboard the bitmap you want to use as a background. 2. Open the page or form. 3. Choose Design - <Design element> Properties and click the Background tab. 4. Click Paste Graphic to display the graphic as the page or form background.
68 Application Development with Domino Designer

To import a bitmap, jpeg, gif, pcx image, or tiff 5.0 bitmap as a background 1. Choose Design -<Design element> Properties and click the Background tab. 2. Click the Import Graphic button and select the file to import. 3. Click OK. To delete a page or form background 1. Choose Design - <Design element> Properties. 2. Click the Background tab then click Remove Graphic. For more information, see Adding a picture in Notes 5 Client Help.

Creating an imagemap
An imagemap is a graphic you enhance with programmable hotspots that perform some action when a user clicks on them. Imagemaps are often used as navigational structures in an application. For example, an imagemap of a plate of food might have hotspots users click to see recipes for the food pictured. Unlike a navigator, which is an independent design element, an imagemap resides on a page or form, so you can easily combine an imagemap with text and other page or form elements, and you can control the display of an imagemap using a hide-when or computed-for-display formula. If you plan to create a sitemap or navigator that combines several graphics with text and action buttons, create a navigator instead of an imagemap. An imagemap can be any graphic you can paste or import into a page or form, with the exception of graphics in the pic format. If you create an imagemap and then need to change the graphic, you can change the graphic while keeping the hotspots intact. To create an imagemap 1. Paste, create, or import a graphic or shared image on a page or form. 2. Select the graphic. 3. Choose Picture - Add Hotspot <hotspot shape>. 4. Click and drag to draw the hotspot on the graphic. Note To draw a polygon hotspot, click the points of the polygon, double-clicking to close the shape. To draw a hotspot around the entire graphic, choose Default Hotspot. 5. Choose Picture - Hotspot properties. 6. On the Hotspot Info tab of the Hotspot <shape> Properties box, specify a link. For information on linking, see Adding links.

Chapter 4: Designing Pages 69

7. (Optional) Specify a target frame where the linked document will display when a user clicks the hotspot. 8. On the Advanced tab add alternate text. 9. (Optional) On the Advanced tab, specify the Imagemap tab order for the hotspot. The tab order specifies the order in which hotspots are selected when a user presses the TAB key. 10. (Optional) In the Script area of the Programmers pane, specify a simple action, formula, or LotusScript or JavaScript routine to run when a user clicks the hotspot. To move a hotspot Once you create a hotspot you can move it as necessary. To move a hotspot do one of the following: Click and drag the hotspot that you want to move. Select the hotspot and use the arrow keys to move one pixel at a time. To delete a hotspot from an imagemap 1. Select the hotspot. 2. Choose Picture - Delete Hotspot. To copy an imagemap You can copy an imagemap from another page or form, form, or document, and Designer will maintain all of the hotspots from the original imagemap. 1. Select the imagemap you want and copy it to the clipboard. 2. Open the page or form where you want the imagemap and choose Edit - Paste. To change the graphic for imagemap 1. Select the current graphic. 2. Choose Picture - Replace picture.

Adding an applet
You can add a Java applet to provide visual interest or additional functionality for example, you might use animation to make your home page or form appealing. Applets can range from programs you build yourself to pre-built programs that you simply drop into a page or form. In Web applications, there may be times when you want to display an embedded object, for example, a view or outline, as an applet rather than as HTML to provide a richer user interface.

70 Application Development with Domino Designer

The Designer elements that you can display as applets are outlines, views, rich text fields, and action bars. For more information, see the documentation for creating an outline applet, view applet, editor applet, or action bar applet. In the case of custom or pre-built applets you want to include in a page or form, follow the steps for inserting, modifying, and running applets described in Including Java applets in an application.

Creating an attachment
Add a file attachment to make the file available for users to launch or detach. You can also create attachments to store files. For example, attach a file for use in a Web application, so that it can be accessed using a Domino URL. For more information about opening an attachment with a URL command, see the topic URL commands for opening attachments, image files, and OLE objects. To create an attachment 1. Open the page or form. 2. Move the cursor to the location where you want to create the attachment. 3. Choose File - Attach. 4. Select the file and click Create.

Embedding elements
Embedded elements are a group of objects and controls that can be embedded on a page or form, form, subform, or document. Elements that can be embedded include: Views Folders Outlines Navigators Date pickers One reason to embed an element on a page or form is to make the applications display consistent for both the Notes client and Web browser. Most design elements have different display properties depending on whether a user views them from a Web browser or from a Notes client. To better control the display and functionality of views, folders, navigators, and outlines, you can embed them on a page or form, form, subform, or document. Embedded elements provides functionality in Web applications that closely resembles functionality already available in Notes applications.
Chapter 4: Designing Pages 71

Embedding makes it easier to design a single application for use by Notes and Web clients. Additionally, embedding lets you combine elements on a page or form and use a full range of design features, including frames, tables, styled text, and graphics, to create a high-impact design.

To add an embedded element on a page or form


1. Move the cursor where you want the embedded element to display on a page or form, form, subform, or rich text field of a document. 2. Choose Create - Embedded Element and select the type of element to embed. 3. (Optional) If available for the element, you can enter a formula that specifies under what circumstances it should display. 4. (Optional) Click the embedded element and choose Element <element> Properties to change the alignment, style, or hide. To delete an embedded element 1. Select the embedded element. 2. Choose Edit - Clear.

Embedding a date picker


You can easily create a custom calendar application by embedding a date picker on a page or form. An embedded date picker displays a monthly calendar. The most common application of this is to display a date picker in one frame of a frameset and a standard calendar view in another frame. Clicking a specific day in the date picker broadcasts a message to the frameset to open the corresponding day in the calendar view, displaying all calendar entries for that day. This feature is not supported on the Web. To embed a date picker 1. Move the cursor where you want the date picker to display on a page or form, form, subform, or rich text field of a document. 2. Choose Create - Embedded element - Date picker.

72 Application Development with Domino Designer

Setting properties for the date picker Choose Element - Date Picker Properties to set: Horizontal and vertical size Font style and color Alignment and spacing Hide-when options

Importing, pasting, or entering HTML


You can use an existing Web page or form as a starting point for a page or form you are designing by importing or pasting HTML from the Web into your page or form. There are three ways to use HTML on a page or form. You can import HTML. When you import HTML, Designer renders it on the page or form already translated from HTML. You can also paste or write HTML directly on a page or form. In these cases, the HTML stays in HTML format, and you must choose Treat contents as HTML in the Page Or Form Properties box. To import HTML To import HTML you must first save it as a file that you can access. When you import HTML to a page or form, Designer will translate the imported HTML and render it already translated from HTML. 1. Open a page or form. 2. Choose File - Import. 3. Select the file containing the HTML you want to import and click OK. To paste HTML 1. Select the content you want to paste from the source of an existing Web page or form or another source. 2. Copy the content to the clipboard. 3. Open a page or form. 4. Choose Edit - Paste. 5. Choose Design - <Design element > Properties. 6. Click the HTML tab and check the Treat contents as HTML setting.

Chapter 4: Designing Pages 73

To enter HTML directly on a page or form 1. Open a page or form. 2. Enter the HTML directly on the page or form. 3. Choose Design - <Design element > Properties. 4. Click the HTML tab and check the Treat contents as HTML setting. When you select the Treat document contents as HTML property, Domino passes all data on the page or form directly to the browser. Domino ignores embedded navigators and folders and any embedded views that dont have the property Treat view contents as HTML selected. To include some HTML on a page or form You can include some HTML on a page or form and mark this text as HTML. Designer will serve it correctly to the browser. 1. Enter or paste HTML on the page or form. 2. Select the text and choose Text - Pass-thru HTML.

Launch properties for pages or forms


To set the launch property for a page or form: 1. Click the Launch tab 2. Set the following auto-launch properties for when a user opens a page or document created with a form: First Attachment First Document Link First OLE Object None 3. Set the frameset that the page or form will be associated with and the frame within that frameset.

74 Application Development with Domino Designer

Programming a page or form


A page or form has events associated with it that you can use to run a simple action, a formula, a LotusScript routine, or a JavaScript program. To see what events are available for a page or form, open the page or form in Designer and look at the list of events in the Objects tab on the Info List in the Programmers pane. Selecting an event makes active the choices you have for programming that event. For example, if you select the onLoad or onUnload events, you must program them using JavaScript. If you select the Window Title event, you must program the event with a formula. For information on each event and an example of how to program them, see the Programming Guide.

Adding HTML header information


The HTML Head Content event on a page or form lets you pass HTML information, such as Meta tag to the Head tag for a document. To add HTML header information 1. In the Programmers pane, click the Objects tab of the Info List. 2. Select the HTML Head Content event. 3. Enter the HTML in the Script area of the Programmers pane. 4. Click the green check mark to validate your work. Example: Adding HTML to the head tag header information This example uses the HTML Head Content event to add the Meta tag keyword with a value of gold to the Head tag in a document.
"<meta name=\"keyword\" content=\"gold\">"

Adding JavaScript header information


Use the JS Header event to store any JavaScript functions that you want to call from other events on the form or page or form. You do not have to include the <SCRIPT> tags. Domino creates those for you and puts the script into the <HEAD> tag of the HTML page or form. To add JavaScript header information 1. In the Programmers pane, click the Objects tab of the Info list. 2. Select the JS Header event. 3. Enter the HTML or script in the Script area. 4. Click the green check mark to validate your work.

Chapter 4: Designing Pages 75

Example: Adding JavaScript header information This example uses JavaScript and cookies to load a page or form into the browser and save a cookie called Cookie_Man in the users cookie file. It also displays a message that shows the number of times a user has visited the site. It uses two functions, doCookie() and getTimes(), written in the JS Header. These functions are called from the onLoad event and the inline script on the page or form. Note The actual expiration date in the code has to be changed to a future date in order to make the cookies work properly. In the JS Header Event enter the following code:
cookieName = "Cookie_Man"; function doCookie() { if(document.cookie) { index = document.cookie.indexOf(cookieName); } else { index = -1; } if (index == -1) { document.cookie=cookieName+ "=1; expires=Saturday, 01-Apr-2000 08:00:00 GMT"; } else { countbegin = (document.cookie.indexOf("=", index) + 1); countend = document.cookie.indexOf(";", index); if (countend == -1) { countend = document.cookie.length } count = eval(document.cookie.substring(countbegin, countend)) + 1; document.cookie=cookieName+"="+count+"; expires=Saturday, 01-Apr-2000 08:00:00 GMT"; } } function getTimes() { if(document.cookie) { index = document.cookie.indexOf(cookieName); if (index != -1) { countbegin = 76 Application Development with Domino Designer

(document.cookie.indexOf("=", index) + 1); countend = document.cookie.indexOf(";", index); if (countend == -1) { countend = document.cookie.length; } count = document.cookie.substring(countbegin, countend); if (count == 1) { return ("<b>"+count+"</b> time before.</b>"); } else { return ("<b>"+count+"</b> times before.</b>"); } } } return ("<b>0</b> times before.</b></b>"); }

The onLoad page or form event contains the following code:


doCookie()

This HTML code is at the bottom of the form, formatted as Pass-Thru HTML text.
<script>document.write("You have visited this site "+getTimes());</script>

Chapter 4: Designing Pages 77

Chapter 5 Designing Forms


This chapter describes designing forms as well as information on designing some special types of forms. This chapter works in conjunction with Designing Pages, which describes elements you can use with either a page or a form.

Forms
Forms, like pages, display information. Everything that can be done with a page can be done with a form. What sets forms apart from pages is that forms can be used to collect information. A form provides the structure for creating and displaying documents, and documents are the design element that store data in the database. When a user fills out the information in a form and saves it, the information is saved as a document. When a user opens the document, the document uses the form as a template to provide the structure for displaying the data. The following are the basic steps involved in designing a form: Decide on the purpose and type of form you need. To do so, consider: The kind of information you want to collect and what elements you will need. How and where the resulting documents, which contain and display the collected information, will appear. Create the form. Add elements to the form. Name the form. Assign its properties. Preview and test the form in the browsers users access it with.

79

Form Elements
Form elements are the components you use to create a forms aesthetics and function. Like pages, forms can contain:
Text Horizontal rules Tables Text is often used to label fields so users understand the purpose of each field. Add horizontal rules to separate different parts of a form, or to make a form more interesting visually. Use tables for summarizing information and aligning elements such as fields and graphics in rows and column. A table placed on a form appears in every document created with the form. A section is a collapsible and expandable area defined on a form. It can include fields, objects, layout regions, and text. An access-controlled section allows only certain users to edit the fields in the section. When you place a graphic anywhere on a form, it appears on every document created with the form. For example, on a form for correspondence, placing your company logo at the top of the form creates a letterhead. Imagemaps are graphics you enhance with programmable hotspots that perform some action when clicked by a user. Imagemaps are often used as navigational structures in an application. Within a form, you can add links to databases, views, specific documents, or URL links that open pages on the Internet. Form actions, buttons, or hotspots automate simple or complex tasks. For more information on creating these elements see Automation in applications. Use Java applets to include small programs, such as an animated logo or a self-contained application, in a form. You can attach files to a form so users can detach files locally or launch them from every document created with the form. Embed the following elements in a form: an outline, view, folder pane, import navigator, navigator, and date picker. Use these elements alone or combine them to control how users navigate through your application. If you have existing HTML or you prefer HTML, you can use it on forms. Use existing HTML by importing or pasting it into your form, or you can write your own.

Sections

Graphics

Imagemaps

Links Automation

Applets Attachments Embedded elements

HTML

For information on including any of these elements in a form, follow the steps given for adding them to a page in Designing Pages.
80 Application Development with Domino Designer

In addition, forms can contain:


Fields Fields are the design element that collect data. You can create fields only on forms. Each field on a form stores a single type of information. A fields field type defines the kind of information a field accepts. You can place fields anywhere on a form. For information about fields, see Designing Fields. A subform is a collection of form elements stored as a single object. A subform can be a permanent part of a form or can appear conditionally, depending on the result of a formula. Subforms save redesign time. When you change a field on a subform, every form that uses the subform changes. Common uses of subforms include adding a company logo to business documents or adding mailing label information to mail and memo forms. For more information on including subforms, see Subforms.

Subforms

Access-controlled You can restrict access to a section by creating an access control sections list. For information on creating an access-control list for a section, see Restricting who can access a section of a document. Layout regions A layout region on a form or subform is a fixed-length design area in which related elements can be dragged and moved easily and can be displayed in ways not possible on regular forms and subforms. A layout region can contain static text, graphics, buttons, and all fields except rich text fields. You can hide or collapse a layout region and all its components under certain conditions. Layout regions are not supported for Web applications. Embedded elements such as the file upload and the group scheduler that require programming support can be used on a form only. For more information, see Embedded elements.

Embedded elements

Forms and documents


When a user creates and fills out the information in a form and saves it, the information is saved as a document. When a user opens the document, the document uses the form as a template to provide the structure for displaying the data. When designing forms, you should consider where and how the resulting documents will be displayed. A form is stored in the database it was created in and used to display all associated documents. However, there may be times when you are mailing a document to a database that does not have the form that was used to create the document. In those cases you can designate the form to be stored

Chapter 5: Designing Forms 81

with each document created from it. Storing the form with each document does consume more memory. When a user opens a document, Domino uses these rules to determine which form to use to display it:
Condition If the form used to create the document is available and there is no form stored in the document and no form formula If a form is stored with the document If the view has a form formula If the form used to create the document is not available in the database Form used to display document The form that was used to create the document. The original form name is stored in a hidden field called Form in the document. To find the value of the field you can check the Document Properties box under the Fields tab. The form stored with the document. (When a form is stored in a document, the form name is stored in an internal field called $Title.) The form is determined by the views form formula. The default form for the database. Each database can have only one default form, which is marked with an arrow in the Forms list.

Storing a form with each document


Storing the form with each document allows the document to display correctly even in a database where the form is missing, renamed, or deleted. This feature uses more system memory and may require as much as 20 times more disk space. It can also cause additional work if you change the form design because there is no easy way to update all of the stored copies of the form. In general, store a form in a document only under these conditions: The database to which documents are mailed or pasted does not contain a copy of the original form. The database to which documents are mailed or pasted doesnt share an alias with the original form. The form contains an embedded OLE object or a subscription, and you want documents to reflect any changes to the object. You selected Include in Search Builder in the Form Properties box and want the forms static text to be searchable. The documents created with this form are stored as encapsulated databases and mailed to cc:Mail users. To store a form with each document 1. Open the form. 2. Choose Design - Form Properties.
82 Application Development with Domino Designer

3. Click the Form Info tab. 4. Select Store form in document. 5. Switch to Database Properties in the drop-down list on the Properties box and select Allow use of stored forms in this database on the Database Basics tab. Overriding the stored form When a form is stored in a document, the form name is stored in a hidden field called $Title. Additional information is stored in the $Info, $WindowTitle, and $Body fields. To use a different form to display the document, create an agent that deletes this stored form information and designates another form to display the document. Shared fields and documents with stored forms If the form contains a shared field, that field is converted to a single-use field in the copy of the form that is actually stored in the document. This ensures that if a copy of the document is stored in a database that does not contain the shared field definition, the field can still be used. In the original form, the field is still defined as shared.

Form formulas
To override the default form selection, write a form formula for a particular view. For example, you can write a form formula that uses one form to display all fields when a user edits a document and a different form that resequences or omits fields when a user reads a document. Since form formulas apply only to a specific view, documents created in other views do not use the form formula. For more information on writing form formulas, see the Programming Guide.

Designating a default form for a database


1. Open the Form Properties box. 2. Click the Form Info tab. 3. Select Default database form.

Alternatives to storing forms


As an alternative to storing the form in a document, you can use the LotusScript Send method to design a form you can mail along with a document. This ensures that the database will have the correct form to display the document but wont need to store the form with each document. For more information on using LotusScript to mail forms with documents, see the Programming Guide.

Chapter 5: Designing Forms 83

Creating a form
To create a form, you must have at least Designer access in the access control list of the database. For information on database access, see Managing Domino Databases. If the form you need is similar to one that exists in the same database, another database, or a Designer template, copy and paste the form and then modify it. If no existing form suits your purpose, create a new form. To create a new form 1. In the open database, click Forms in the Design pane and click the New Form button. 2. Design the form. Create fields, text, and other elements on the form. 3. Choose Design - Form Properties to assign a name and other form properties. To copy an existing form 1. In the Design pane, click Forms. 2. From the list of forms in the Work pane, select the form you want to copy. 3. Choose Edit - Copy to copy the form to the clipboard. 4. Open the database you want to copy the form into and click Forms in the Design pane. 5. Choose Edit - Paste to paste the copy into the list of forms in the target database. If you are copying a form from a different database, resources such as shared field definitions and shared images are not sent with the copied form. You must copy resources separately to the new database to avoid an error message. Special types of forms There are several types of forms that you can create for specific purposes. See the following topics for information on creating any of these types of forms. Profile forms Forms that prompt users for input Forms for a Domino billing application To delete a form Remove a form when users no longer need it. After you delete the form, documents that were created with the deleted form are displayed with the default form instead. After you delete a form, to prevent users from seeing
84 Application Development with Domino Designer

a message that the form cant be found when they open existing documents, create an agent that reassigns the form name. For information on using agents to reassign documents to a new form, see Adding automation to your application. 1. Open the database. 2. In the Design pane, click Forms. 3. Select the form you want to delete. 4. Press DEL or choose Edit - Clear.

Tips for designing forms


Placing elements on the form Use the ruler to set tabs and to position elements. Choose View - Ruler to see the current paragraph settings. Use tables to align elements on a form. Nested tables give you very precise control over how you present content. In addition, you can use tables to create certain text effects, such as having text wrap around a picture. Group related information together. Use sections for approvals or other special access needs. Create subforms that group design elements you use in multiple forms. When designing multiple forms for an application, locate particular fields, especially data such as name, department, current date, and due date, in a consistent place and a consistent order. Place hidden fields together at the bottom or top of a form. Assign a different text color to hidden fields. Computed fields are evaluated from the top down and left-to-right. Place dependent fields after the fields they depend on. Forgetting this rule is a common source of problems. Use centered text at the top of a form only. It tends to get lost when used farther down on the form. Use consistent spacing between elements, and avoid crowding the information together. Hide elements that users dont need to see when they are editing, reading, or printing. In particular, hide nonessential graphics while printing. Provide actions and hotspots to let users take action quickly. Use collapsible sections to organize a form and make it easier for users to see the information they need. Set the section properties to expand the section in one context and collapse it in another.
Chapter 5: Designing Forms 85

Naming forms
Each form in a database must have a unique name. If you make a copy of a form and paste it into the same database it came from, Designer will automatically prepend Copy of to the form name to keep the names unique. If you create multiple databases that contain the same information, use the same names for the forms. Standard names enable users to recognize commonly used forms; they also make it easier for users with similar databases to communicate. For example, suppose you have four customer-tracking databases, one in each regional sales office. If the Southern regional manager wants to discuss a shared account with the Western regional manager, both managers should know what a Company Profile document is. To name or rename a form, choose Design - Form Properties and enter a name for the form. Name requirements The name is case-sensitive and can be any combination of characters, including letters, numbers, spaces, and punctuation. The full form name, including all synonyms and the cascading name, cannot exceed 256 bytes. If youre using multibyte characters, 256 bytes is different from 256 characters. Only the first 64 characters of a form name appear in the Create menu.

Creating aliases
A form can have additional names (aliases). Using aliases lets you change the form name that appears on the Create menu without having to rewrite every formula that references a form name. It also lets you reassign existing documents to the new form, and rewrite formulas or reassign documents if the form name is translated. The the form name and its aliases are separated by a vertical bar |. If a form has only one name, it appears on the Create menu and in the documents FORM field. If there are two or more names, the forms first (leftmost) name always appears on the Create menu, while the forms last (rightmost) name, which is typically the alias, appears in the FORM field. Sometimes a form can have multiple names usually due to translation. In those cases the middle names are ignored. As long as the alias does not change, documents will display using the original form and all formulas referencing the form will continue to work.

86 Application Development with Domino Designer

To add an alias 1. Choose Design - Form Properties. 2. In the name field on the properties box, add a | (vertical bar) to the right of any other names. In the following example, Interview is the alias and Main Topic is the original name:
Main Topic | Interview

Form names and keyboard shortcuts


Windows users can select a menu item quickly by typing its keyboard shortcut (an underlined letter). If each form begins with a different letter, the keyboard shortcut is easy to see on the Create menu. To specify the keyboard shortcut, type an underscore (_) before the letter that you want to use. Each keyboard shortcut must still be unique within the form list. For example, to force the letter v as the keyboard shortcut for the Interview form, enter the name as:
Inter_view

Ordering forms on the Create menu


A form structures the data for a document that a user creates. In a Notes client application, a user chooses a form from the Create menu to create a new document. The Create menu sorts form names in alphabetical order. To display the forms in a different order for example, with the most frequently used form appearing first precede the form name with a number or a letter to force the forms into the correct sequence. If a database has too many forms to display all the forms neatly on the Create menu, you can design a cascading menu to group the related forms under one menu item. The Mail (5.0) template uses cascading workflow forms. When users choose Create - Workflow, they see these form choices: Workflow\Bookmark Workflow\Phone Message Workflow\Task To create a cascading menu for Notes clients 1. Open the form. 2. Choose Design - Form Properties. 3. In the form name box, enter the name of the menu item you want to appear at the top level, followed by a \ (backslash) and the form name. To define an alias for a cascading form, insert the alias after the form name, as in: Service Request\Hardware|HW, where HW is the alias. 4. Make sure the option Include in Menu: Create menu is checked.
Chapter 5: Designing Forms 87

To move a form to the Create - Other menu in Notes client If you dont expect a form to be used frequently, move it to the Create Other dialog box to shorten the list of forms in the main Create menu. 1. Open the form. 2. Choose Design - Form Properties. 3. On the Form Info tab, select Include in Menu and select Create Other dialog. To remove a form from the Create menu in Notes client Removing a form from the Create menu hides the form from all users. For example, the Mail template hides the NonDelivery Report and Return Receipt forms because only the Notes Mail Router uses them. For compatibility with earlier releases of Notes, putting parentheses around the form names when you name a form will also remove forms from the Create menu. 1. In the Form Properties box deselect Include in Menu. 2. Save the form. To hide a form from only some users, use a create access list. For more information about create access lists, see Managing Domino Databases. To hide a form Another way to remove a form from the Create menu is to hide it. Hiding allows you to specify conditions under which the form is hidden or displayed. For example, you can hide a form from Notes clients, but display it for Web clients. 1. Close the form you want to hide. 2. In the Design pane, click Forms in the Design pane. 3. From the forms list, select the form you want to hide. 4. Choose Design - Design Properties. 5. Click the Design tab. 6. Select a hide option.

Making a form available to Web browsers


In Web applications, users do not have access to the Notes menu structure, so you must provide a mechanism for users to create and edit documents. For example, you might design a view action users use to create a document, and a button on the form to edit the document.
88 Application Development with Domino Designer

The following screens compare how a new document appears to Netscape Navigator users and Notes client users.

To make a form available to Web users You must use this technique to allow Web users to create a document from a form, but it also works in Notes applications. 1. Add a button, action, or hotspot to a form. 2. In the Programmers pane, choose the Click event and program the event with a formula or script that creates a document from the form. For example, this formula opens a new Main Topic document in the current database:
@Command([Compose];"Main Topic")

Use this formula to compose a document in the current database:


@Command([Compose];"formname")

Use this formula to compose a document from another database:


@Command([Compose];"":"database";"formname")

Chapter 5: Designing Forms 89

Selected form properties


You can use the Form Properties box to set form attributes. To open the Form Properties box 1. Open the form. 2. Choose Design - Form properties. Protecting author/editor anonymity If you want a documents author or editors to remain anonymous, define a form that doesnt record the names of people who create or edit it. For complete anonymity, be sure that the author name does not appear elsewhere on the document for example, in a visible computed field. On the Form Info tab, select Anonymous Form. Consolidating replication conflicts A replication-or-save conflict occurs when users in different locations edit the same document. One version becomes the main document, and the others become conflict documents that are marked with a diamond in the view. You can design a form that merges replication conflicts into a single document where possible. In this case, if two users edit different fields in the same document, Domino saves the edits to each field in a single document. However, if two users edit the same field in the same document, Notes saves one document as a main document and the other document as a response document marked as a replication conflict. On the Form Info tab, select Merge replication conflicts. For more information on replication conflicts, see Notes Help. Opening documents in edit mode automatically For users convenience, you can specify that documents created with a form automatically open in edit mode. On the Defaults tab, select On Open: Automatically enable Edit Mode. Generating HTML for hidden fields When checked, this form property generates HTML information about hidden fields on a form. This allows document behavior in a Web application to more closely match document behavior in a Notes application. For example, if you create a form that relies on a hidden field for a calculation, that form may not behave as expected in a Web application in certain situations. By generating HTML for the fields, the information is available for Domino to successfully complete the
90 Application Development with Domino Designer

calculation. The HTML generated for the hidden fields is also accessible through JavaScript, so you can change the value or find out the state of a hidden field with a script. Checking this option creates larger files on the Web and may decrease application performance. Consider security, since information in hidden fields, though not visible in the browser, is visible through the View Source menu item on the browser. To generate HTML for hidden fields On the Defaults tab, in the For Web Access section, check the option Generate HTML for all fields and deselect the option Treat document contents as HTML. Defining a header on a form If you are designing a form for use in a Notes application, you can define a header that does not scroll off screen when the user scrolls down the form or document created with that form. For example, in the Notes mail template, a header displays all of the information contained in the mail sender and recipient fields. This section remains static while you scroll through a mail message. Headers can contain any element that a form can contain. The only caveat is that a table cannot be the first element in a header; it must be preceded by a text object, even if the text object is blank. 1. Enter the text, graphics, tables, or other elements you want in the header region of the form. 2. Move the cursor to the line below where you want the header to start. 3. Choose Design - Form Properties. 4. On the Header tab, select "Add header for form," to mark off the header area. 5. Set the display properties for the header. Height can be set in pixels as a percentage of the form height, or to fit contents. Select a scrolling option. Auto automatically turns scrolling on when the content of the header exceeds the space allotted. Allow resizing lets users resize the header area. Border controls the display of the dividing line between the header and the body of the form. You can turn the border off or change the thickness and color. Displaying a graphic in a header To display a graphic in a header, add a background graphic to the form. This becomes the background for the header only. Note that if you do this, the remainder of the form is blank and cannot display another background graphic.
Chapter 5: Designing Forms 91

Creating a print header and footer You can define a header and footer that will print on all documents created with that form. Headers and footers are not supported for Web applications. 1. On the Printing tab, click Header and type the header and/or click Footer and type the footer. 2. Click the icons to add the page number, date, time, and so on. 3. (Optional) Assign a font, size, and style for header or footer text. Header and footer alignment Headers and footers have three preset, permanent tab stops: left, center, and right. When you insert one tab, text to the left of the tab is left justified, and text to its right is right justified. With two tabs, text to the left of the first tab is left justified; text between the two tabs is centered; and text to the right of the second tab is right justified. For example: &D|&T|&P Left justifies the date, centers the time, and right justifies the page number. |URGENT| Centers the text URGENT. ||URGENT Right justifies the text URGENT.

Creating a response hierarchy


If you are creating an application that requires users to create a document and then post responses to that document, and responses to the responses, you will need to set up a hierarchy between the forms. There are three types of forms you can designate: Main topic form - The top level in a hierarchy of forms. It can have zero or more response forms associated with it. Response form - Creates response documents associated with a main document. In a view, response documents appear under whichever main document is highlighted when the user composes a response. Designers often create response documents that inherit data from the main document for example, the topic title. Response-to-response form - Creates response documents associated with either a main document or a response document. A form creates main (parent) documents unless you designate it as a form that creates response documents. For information on indenting response documents under its parent document in a view, see Designing Views.

92 Application Development with Domino Designer

To designate a response or response-to-response form


1. Open a form. 2. Choose Design - Form Properties. 3. In the Type field on the Form Info tab, do one of the following: Select Response as the type to use the form to create responses to main documents. Select Response to Response as the type to use the form to create responses to main documents and other responses. To inherit a parent document into a new document To make it easy for users to find a related document, a document can inherit a parent or related document as a link, as collapsible rich text, or as rich text. For example, a new response document can include a link to its main document. A link takes up less disk space than including the full or collapsed contents of a parent document because Domino stores only a pointer to the document rather than a copy of the document. Once inheritance is enabled, whichever document is highlighted when the user chooses Create - <response/new form name> becomes the parent document. The documents do not need a main document/response document relationship, whichever document is highlighted is assumed to be the parent document. A user can suppress inheritance by pressing CTRL while choosing Create. 1. Open the form. 2. Create a new rich text field to display the document or link. 3. Choose Design - Form Properties. 4. Click the Defaults tab. 5. Select On Create: Inherit entire selected document into rich text field. 6. Select or enter the name rich text field you created in step 2. 7. Select one of the following: Link Collapsible rich text Rich text 8. (Optional) Select On Open: Show context pane and Parent.

Version tracking
Version tracking allows you to maintain a history of changes to a document. In order to activate version tracking, you must designate the form used to create documents as a version-tracking form.

Chapter 5: Designing Forms 93

To designate a form for version tracking


1. Open the form. 2. Choose Design - Form Properties. 3. On the Form Info tab, select a Versioning method and a Create versions option. There are different versioning methods:
New versions become responses Use this when the original document is the most important. The original document is listed first in the view; all successive versions follow. Choose this method if the original document is the focal point of the view, with responses being used for reference. When new versions become responses, you can prevent replication or save conflicts in the view. If users on different servers modify and save the main document, their versions are treated as two separate response documents when the databases replicate. The two responses are displayed in the view in chronological order. Prior versions become responses Use this when the new version is the most important. The latest version is listed first in the view; previous versions and the original follow. Use this if the update is the most important or most frequently read document and you want to store older versions as a backup or for historical reference. When prior versions become responses, you cant prevent replication or save conflicts. If users on different servers modify and save the main document, the two new versions of the document appear as conflicting main documents when the databases replicate. New versions become siblings Use this when all versions have equal importance. The original document is listed first in the view; all successive version follow as additional main documents without introducing the risk of replication or save conflicts. This method is also useful when revisions arent based on a historical or subordinate model for example, in a form where workgroup members create their own replacement versions of an original document or where the original document is used as a template for each new document. This method is most effective when you dont expect every main document to be revised, since it is hard to find updates in a view where many new documents have been created in the updating process. To distinguish a revised document from the original document, add identifying information, such as New Proposal or Revised to the field that displays in the view.

94 Application Development with Domino Designer

There are two create versions options:


Manual - File, New Version Manually creates a new version of the document only when the user chooses File - Save As New Version. This option allows the user to choose when to create a new version and when to overwrite the existing document. Automatically creates a new version of a document each time the user saves a document.

Automatic - File, Save

Make sure users understand that version tracking is active, so that they understand the impact of editing documents. Explain version tracking in the Using Database document. If there is a response hierarchy set up in the database, responses to version-controlled documents display as responses to the original document only.

Customizing a forms window title


The window title is the text that appears in the title bar when you compose, read, or edit a document. By default, the word Untitled appears in the title bar. To help users understand the context of the document theyre reading, create a descriptive window title. A window title can be static that is, it always displays the same message or dynamic that is, it displays a message that changes based on a formula you create. An example of a dynamic window title is a title for a main document in a discussion database that includes the number of responses to the document. The title changes each time a new response gets created. To create a window title, you write a formula that supplies the text to display. The text can be a text string you enter directly, text that results from a function, or the contents of any field type except rich text. If the field does not contain text or if a function does not return text, you must convert the value to text using the @Text function. For example, the following formula converts the date value in the DateCreated field to a text value for display in the window title:
"Response created on " + @Text(DateCreated);

To customize a forms window title 1. Open the form. 2. On the Object tab of the Info List in the Programmers pane, select the Window Title - attribute. 3. In the Script area of the Programmer's pane, enter text enclosed in quotation marks or a formula that evaluates to text.
Chapter 5: Designing Forms 95

4. Click the check mark to save the formula. 5. To test the window title, create, save, and read a new document. Make sure the title is appropriate for all three situations. For more information on creating window title formulas, see the Programming Guide. Examples: Customizing window titles Title includes creation date and company name This formula displays the date the document was created, form name, and company that was billed. @Text converts the date to a text string, and the extra spaces within the quotation marks force the words in the title to be properly spaced.
@Text(@created) + " Inventory Invoice for " + CompanyName

This formula uses the field form to refer to the form name instead of hard coding it into the formula.
@Text(@created) + " " + form + " for " + Company Name

Title includes number of responses This formula is useful for a main document form in a discussion database.
@If(@IsNewDoc;"New Topic";Subject + @DocDescendants(" (No Responses)";" (1 Response)";" (% Responses)));

If the document has never been saved, New Topic shows in the title bar while the user composes the document. After the document is saved, the title is the subject combined with the number of responses. If the subject is Icebox 2000 and there are no responses, the title of the document is Icebox 2000 (No Responses). With one response, the title becomes Icebox 2000 (1 Response). With two responses, the title becomes Icebox 2000 (2 Responses). Response includes the subject When the response or response-to-response is first composed, this formula displays New Response To and the subject of the main document.
@If(@IsNewDoc;"New Response to " + Subject; "Response " + @DocNumber("") + " of " + @DocSiblings + " to " + Subject);

When a user reads the response, the window title displays the total number of responses to the main document, the response being displayed, and the subject of the main document. For example, if the response document is the second of four responses to Icebox 2000, the title displays as Response 2 of 4 to Icebox 2000.

96 Application Development with Domino Designer

Subforms
A subform is a collection of form elements that are stored as a single object. Subforms can contain the same elements as regular forms. Subforms save redesign time. When you change a field on a subform, every form that uses the subform updates. Common uses of subforms include adding a company logo to business documents or adding mailing label information to mail and memo forms. A subform can be a permanent part of a form or can appear conditionally, depending on the result of a formula. For example, you might offer users a choice of custom mail forms with different graphics and styles for various types of mail messages, such as memos, alerts, or letters. Field names used in the subform cant be used elsewhere on the form. Changes you make to a subform affect all forms and documents that use the subform.

Creating a subform
You can copy and modify a subform that is similar to the one you need or create a new subform and design it yourself. 1. Select the database that will have the new subform and click Resources - Subforms. 2. Click the New Subform button. 3. Create the subform using the same elements you use to create a form. 4. Choose Design - Subform Properties. 5. Enter a name for the new subform. 6. Choose display options for including the subform in the Insert Subform or the New Form dialog box. 7. Close and save the subform. Display options for subforms The following options do not apply to computed subforms. Select Include in Insert Subform dialog so designers see it when inserting a subform. Excluding a subform from the Insert Subform dialog box is not a security measure. Users with Designer access or higher can open any subform in Designer and copy individual components. Select Include in New Form dialog if you want the subform to appear immediately when designers choose Create - Design - Form.

Chapter 5: Designing Forms 97

Displaying a subform on a form


To insert a subform 1. Open the form. 2. Click where you want to paste the subform. 3. Choose Create - Insert Subform. 4. Select the subform you want and click OK. To display a computed subform 1. Open the form. 2. Click where you want to paste the subform. 3. Choose Create - Insert Subform. 4. Select Insert Subform based on formula. 5. Click OK. 6. Enter a formula in the Programmers pane that determines which subform to display. 7. Close, name, and save the form. Example: Displaying a computed subform In the Main Topic form of a discussion database, you want to display the NewDocSubform if a document is new and the SavedDocSubform if the document has been saved. Each subform contains different fields and graphics. The Insert Subform formula is:
@If(@IsNewDoc;"NewDocSubform";"SavedDocSubform");

Deleting subforms
When a user opens a document that references a deleted subform, the message Subform: <subform name> not loaded appears on the status bar. The document opens without any representation of the deleted subform. When a designer opens a form that references a deleted subform, the message Subform: <subform name> not loaded appears on the status bar. When a designer clicks the deleted subform area on the form, the message Invalid or nonexistent document appears and the designer cant open the subform. To avoid these messages, add another subform to the database and give it the same name as the deleted one.

98 Application Development with Domino Designer

To delete a subform from a form You can remove a subform from an individual form, without disturbing other forms that use it. 1. Click the subform area on a form. 2. Choose Edit - Clear. 3. Adjust the formatting if necessary. To delete a subform from a database You can remove all instances of a subform from a database. Be aware that this will cause errors in any form that refers to the subform. 1. Click Subforms in the design list for the database. 2. Choose Edit - Clear.

Layout regions
A layout region is a design area on a form that affords flexibility for combining and arranging text and graphics. Layout regions are not supported in Web applications. A layout region can contain: Text Graphics (either in the background or as graphic buttons) Fields (except rich text fields and dialog list fields) Buttons You cannot add the following elements to a layout region: Attachments Horizontal Rules Hotspots Java Applets Links OLE Objects Page Breaks Pop-ups Sections Shared Actions Shared Fields Subforms Tables
Chapter 5: Designing Forms 99

You can hide or collapse a layout region and all its components under certain conditions. For example, you can hide a layout region when Web users view the application, or when users edit the form.

Creating a layout region


To create a layout region 1. Open the form. 2. Move the cursor to the location in the form where you want to place the layout region. 3. Choose Create - Layout Region - New Layout Region. To delete a layout region 1. Click the layout region and choose Edit - Clear. 2. Adjust the formatting if necessary.

Aligning and rearranging elements in a layout region


1. Open the form. 2. Click the layout region and choose Design - Layout Properties. 3. Click Show grid to see the current spacing between elements. 4. Do one or more of the following: Click Snap to grid to align all elements with the grid. Change the grid size if you want a narrower or wider arrangement of elements. Click and drag an element to move it to a new location within the layout region. Click an element and choose Design - Send to Back to move it behind other elements. Click an element and choose Design - Bring to Front to move the element on top of others.

Changing the size and style of a layout region


You can adjust the size, position, and look of a layout region. 1. Open the form. 2. Click the layout region and choose Design - Layout Properties. 3. Select a different Left setting to move the layout region horizontally. Elements within the layout region stay in a fixed position, relative to the borders of the layout region. 4. Select a different Width or Height setting to size the layout region perimeter.
100 Application Development with Domino Designer

5. (Optional) Deselect Show border to make the layout region borders invisible. 6. (Optional) Select 3D style to show the layout region in gray and to show fields and buttons as they look in dialog boxes.

Adding a graphic to a layout region


1. Move the cursor to approximately where you want the graphic to be in the layout region. Once the graphic is in, you can move it by dragging it. 2. Choose Create - Picture and select the graphic file. 3. Select either Graphic or Graphic button. 4. Edit the layout options to change the size or position of the graphic. 5. (Optional) Click the Hide tab to adjust the hide properties. 6. (Optional) Choose Design - Send to Back to position the graphic behind other elements.

Adding a graphic button to a layout region


A graphic button adds a hotspot to a layout region. 1. Copy a graphic to the clipboard. 2. Move the cursor to approximately where you want the graphic button to be in the layout region. Once it is pasted in, you can move it by dragging it. 3. Choose Create - Layout Region - Graphic button. 4. From the Objects tab on the Info List in the Programmers pane, select Hotspot - Click. 5. In the Script area of the Programmers pane, enter a formula for what you want the hotspot to do. 6. Edit the layout options to change the size or position of the graphic button. 7. (Optional) Click the Hide tab to adjust the hide properties. 8. (Optional) Choose Design - Send to Back to position the graphic behind other elements.

Chapter 5: Designing Forms 101

Embedded Controls
There are two types of embedded controls that can only be used on a form: The file upload control - allows you to create a form so that Web users can attach files to documents The group scheduler - allows you to create a form that displays the schedules of specified users

Adding a file upload control


To allow Web users to attach files to documents, include a file upload control on a form. When Web users create a form or open a document in edit mode, they can attach a file by typing the path and file name or by clicking Browse and selecting a file from the filing system. The server administrator must also define a temp directory on the server. If the directory doesnt exist, the attachment is not saved with the document. The file upload control is not supported in the Notes client. 1. Open the form to which you want to add the file upload control 2. Move the cursor where you want the upload control to display. 3. Choose Create - Embedded Element - File upload control. 4. Select the control and right click to open the File Upload Control Properties box. 5. On the Hide tab select, Hide paragraph from Notes R4.6 or later.

Adding a group scheduler


The group scheduler allows you to design a form for the Notes client that displays the schedules of users. For example, you can create a form for users to schedule department meetings. Embedding a group scheduler on the form lets users check everyones schedules before planning the meeting time. Also, within the group scheduler users can click on a persons name to open that persons calendar view (provided the user has been given access in the persons mail preferences). You can program the calendar to open in a separate frame, or in its own window. There are three parts to using group scheduler: Embed the group scheduler on a form. Create the fields that collect the data for the group schedulers display. Program the group scheduler to retrieve the data from the fields.

102 Application Development with Domino Designer

Creating a group scheduler on a form Only one group scheduler can be embedded per form. 1. Open or create a form for the group scheduler. 2. Move the cursor where you want the group scheduler to appear on the form. 3. Choose Create - Embedded element - Group Scheduler. Note The group scheduler does not display scheduling information while you are designing the form. Creating fields for the group scheduler The group scheduler needs three pieces of information before it can display anyones schedule. Whose schedule to display (individuals or group). What week to start the schedule information from. How many hours per day of schedule information to display. One way to collect this data is to create editable fields on the form and have users enter in those fields the information they want displayed. You can also use LotusScript or the Formula language to create the field items. For an example of collecting the data using an action button and Formula language, look at the GroupScheduler form in the Mail5.0 Template. Once you have created the fields or other method for collecting the data, associate those fields with the Group Scheduler attributes. Programming the group scheduler Once you have created the fields for collecting the data, you must program the group scheduler so that it can retrieve the data from the fields. The group scheduler has three attributes that must be programmed: Group member items Points the group scheduler to where the data is for whose schedules are displayed Start time item Points the group scheduler to where the data is for the week the scheduler should start the display from The group scheduler displays one week of scheduling information at a time. The Notes Preference settings for the user accessing the form determines the day of the week that the display starts on. Duration item Points the group scheduler to the data that determines how many hours to display for each day

Chapter 5: Designing Forms 103

To associate the fields with the attributes, select the attribute from Objects tab of the Info List and enter a field name in quotation marks in the Script area of the Programmers Pane.

Group Member items When a user creates a form containing the group scheduler, the group scheduler evaluates the contents of this attribute to determine the location of the data that indicates whose schedules to display. When the group scheduler finds the field, it returns scheduling information for those people whose names or group name is specified in the field. If the contents of the field contains a group name, the group is expanded into its individual members, each of whose scheduling information is displayed. If you are writing a LotusScript formula to obtain the data for this attribute, the formula must evaluate to a text list of one or more field names. Start Time item When a user creates a form containing the group scheduler, group scheduler examines the contents of this attribute to determine where to find the data for the date and time on which to begin the display. The value of this field should be a date and time. If the value is not a date and time, the current date and time of the users system is the default. If the value is a date only, that date and the current time on the users system are the default. If the value is only a time, that time and the current date on the users system are the default. When a user accesses the form, the scheduling information starts from the specified date. The user can change which week is displayed by clicking on the left and right arrow keys. Each day will begin at the specified time. The time is rounded down to the nearest hour. Note The schedules are displayed in terms of the users local time zone for example, a Pacific time zone user free between 9 and 5 PST will appear free between 12 and 8 to an EST user.

104 Application Development with Domino Designer

Duration item This attribute is examined to determine where to find the data for how many hours of each persons schedule to display. The value of this field should be an integer between 1 and 24, inclusive. A value less than 1 will be defaulted to 1 and a value greater than 24 will be defaulted to 12. Setting a refresh mode When a user creates a document that contains a group scheduler, the group scheduler retrieves the scheduling information from the mail servers of the group members. The user can change any of the scheduling information displayed by changing the values in the fields. When any of the information in the fields used by the group scheduler changes, the user must refresh the document to see the changes reflected in the scheduler display. The default refresh mode is a full refresh. That is, whenever a user refreshes, all three pieces of scheduling information are updated regardless of which fields have been changed. This includes retrieving the scheduling data for all group members. Therefore, it could unnecessarily affect performance if all a user did was change the value in the duration field. To limit the refresh, add an optional, reserved field on the form named $GroupScheduleRefreshMode. This field controls how the group scheduler refreshes the scheduling information. The value of $GroupScheduleRefreshMode can be 0 or 1. If the value of $GroupScheduleRefreshMode is 0, the group scheduler performs a partial refresh which refreshes only data in the field that has changed. This is useful when the users have added or deleted a group member or changed the duration item or start time item. If the value of the $GroupScheduleRefreshMode field is 1, group scheduler will update all data for all members on refresh. Displaying the legend You can create a reserved field on the form that contains the group scheduler to allow users to turn the legend off or on. The reserved field name is $GroupScheduleShowLegend. Valid values are 0 (to turn the legend off), and 1 (to display the legend). Setting properties for the group scheduler Use the Group Scheduler Properties box to set the following properties for the group scheduler: Target frame - Clicking on a group members name in the group scheduler opens that members calendar in its own window. You can specify a target frame to display group members calendar views and appointment documents.

Chapter 5: Designing Forms 105

Size - Set the horizontal size as either a percentage of the window width or a fixed width. Set the vertical size to fit to contents (number of group members) or a fixed height. If you select fixed height, the scheduler displays a scroll bar if all of the members do not fit on the screen. Color - The group scheduler uses a number of colors to display calendar information. All of the colors can be customized on the Background tab of the properties box. For an example of a group scheduler form, see the Group Calendar form in the Mail (R5.0) template.

Profile forms
Profile forms are forms that collect user-specific or database-specific values. These values are stored and retrieved in Profile documents. What sets these documents apart as profile documents is not the form they are created with, but rather the way the documents are displayed and values in the fields passed back. Only one profile document per form can exist for each user of a database. Or, only one profile document can exist for a database if that form is available to all users. Profile documents allow for quick data retrieval, because they are cached while the database that stores them is open. Profile documents are like other database documents except they are somewhat invisible they do not display in views and are not included in a document count for the database. Users create profile documents through an action button or agent you design that uses LotusScript or the formula language. A database can have a single profile document or multiple profile documents that match a key you specify for example, an @username key that creates one profile document for each user of a database, or a key that specifies a different profile document for each day of the week. Whether you use one profile document for a database or use multiple profile documents depends on your design needs. Use a single profile document to contain settings that all documents in the database need, such as environment variables. Use multiple profile documents for more customizable settings, such as user preferences. A user must have at least Author access in the access control list (ACL) of a database to create a profile document that is available to all users. You can use any form to create a profile document. After creating the form, you create a button, action, or agent for the application that uses either @CommandEditProfile in a formula or UIWorkspace.EditProfile or NotesDatabase GetProfileDocument in a LotusScript program to create or retrieve a document. In each case, Notes looks for a profile document with the form name you specify, and creates a profile document if one does
106 Application Development with Domino Designer

not already exist. For an example of a profile document, see the Interest Profile form in the Discussion - Notes & Web (R5.0) template. For more information about accessing or editing a profile document using Formula language or LotusScript, see the Programming Guide.

Creating a profile form


1. Create a form with fields to hold the values you want to store in profile documents. 2. Choose Design - Form Properties and deselect Include in Menu. 3. Save the form. 4. Do not include the form in any view. For more information, see Designing Views. 5. Create a button, action, or agent that uses either the LotusScript NotesDatabase GetProfileDocument method or UIWorkspace.EditProfile, or the Formula language @Command EditProfile to create or access the document. See the Programming Guide for more information about Formula language and LotusScript. You can create or edit a profile document using @Command([EditProfile]) or @SetProfileField. You can retrieve field values from an existing profile document using @GetProfileField. For full syntax descriptions, see the topics for these commands in Help. Use the SetProfileField and GetProfileField commands to set and retrieve field values from a profile document. A SetProfileField command also creates a profile document if none exists. You cannot delete a profile document using an @command or @function. Use LotusScript if you must delete a profile document. If you prefer scripts to formulas, use LotusScript routines to create and edit profile documents. The EditProfile method of the NotesUIWorkspace class produces the same result as the @Command([EditProfile]) command used in a formula. To set or retrieve field values for a profile document with a script, use the GetProfileDocument method to get a handle to the document. You can then retrieve values from the document or set new ones, just as you would with any document. Use the IsProfile property for the NotesDocument class to determine if a NotesDocument object is a profile document. Use the NameOfProfile property to retrieve the name of the profile document. For information on creating or editing profile documents using an @Command formula or a LotusScript program, see the Programming Guide.
Chapter 5: Designing Forms 107

Designing forms that prompt users for input


You can create forms that prompt users for input. For example, you can create a form that mimics the behavior of a dialog box. Use this kind of form to collect user input to populate fields in a host form.

Designing a form that presents a dialog box


To help users to fill out documents, create a custom dialog box that prompts for specific input. You can do this by using the @DialogBox function or LotusScript. Using @Dialog requires two forms: one, the dialog form, has a layout region that contains fields, text, and graphics, and looks like a dialog box; the other, the host form, contains a button that uses @DialogBox to display the dialog form. The two forms contain shared fields, and when users enter field values in the dialog form, the values are shared with fields on the host form that have the same names. For example, a host form called Memo has a button that uses @DialogBox to bring up the dialog form called Memo Options. Both forms have a field called Comments. Text entered into the Comments field in the Memo Options form also appears in the Comments field in the Memo document. When using @DialogBox, all values entered in the dialog box are stored in the document created with the host form and can be seen in its Document Properties box even if the fields do not appear on the host form. If the keyword [NoNewFields] is used with the @DialogBox function, the fields that are on both the host form and the dialog form will be updated when the dialog form is saved or refreshed. If [NoFieldUpdate] is used, no fields or field values from the dialog box form will be updated on the host form. Layout regions are supported in Notes applications only. To create a dialog form for use on the Web, design the dialog form with a table instead of a layout region, and follow steps 8 through 11 for calling the dialog form from a host form. 1. Open or create the dialog form. 2. Choose Create - Layout Region - New Layout Region. 3. Drag the layout region to the dialog box size you want. 4. Choose Design - Layout Properties. 5. Deselect Show border and select 3D style. 6. Click the layout region and then create the graphics, text, and fields for the dialog box. 7. Close and save the form. 8. Double-click the host form that will display the @DialogBox button. 9. Click where you want to add the button, and choose Create - Hotspot Button.
108 Application Development with Domino Designer

10. On the Display tab, add a label and width for the button. 11. In the Programmers pane, click Formula, and write a formula using @DialogBox Include the name of the dialog form. For information on using @Dialogbox, see the Programming Guide. Guidelines for designing a form that presents a dialog box To match the Notes user interface as closely as possible, follow these guidelines: For the dialog form, use a layout region with the 3D property selected. Although you can design the dialog form in any way, a 3D layout region most closely resembles a dialog box. A layout region that is 3 inches square is big enough to display a few fields and two or three buttons. In the @DialogBox formula, include the [AutoVertFit] and [AutoHorzFit] options to size the dialog box to fit the layout region. Use 9 point Helvetica for static text, fields, and buttons. Place static text labels above or to the left of fields and end them with a colon (for example, Name:). Place buttons at the bottom of forms. OK and Cancel buttons appear automatically to the right of the layout region. If you do not want the cancel button to appear, use the @DialogBox keyword [NoCancel]. If you do not want the OK or the Cancel button to appear use [NoOkCancel]. To arrange choices horizontally, use the multi-column display option with radio button and check box field; use None for the frame option so choices blend with the dialog box background. For button text with multiple words, use initial capital letters. Use ellipses for buttons that lead to another dialog box or task for example, Show Details...

Designing a form that prompts users for information


You can design a form that uses @Prompt to request information from users to help them fill out a document. This function is similar to @DialogBox, but it is simpler: @Prompt contains only text and doesnt interact with any other forms. 1. Create a field, button, hotspot, or action that will store the @Prompt formula. 2. Double-click the field, button, or hotspot. 3. In the Programmers pane, select Run Formula.
Chapter 5: Designing Forms 109

4. Enter a formula in the Script area using @Prompt. 5. Close and save the form. For more information on the @Prompt command, see the Programming Guide. Examples: Using @Prompt [YesNoCancel] This formula displays a warning before sending the memo and gives the user a chance to select Yes, No, or Cancel.
Result := @Prompt([YesNoCancel]; "Send memo?"; "This memo will be sent to everyone listed in the To, CC, and BCC fields." );

[OkCancelEdit] This formula fills the Name field with the users response to the prompt. The default value is the users Notes name. If the user selects Cancel, Notes cancels the formula evaluation.
FIELD Name := @Prompt([OkCancelEdit]; "Enter Your Name"; "Type your name in the box below."; @UserName);

[OkCancelList] This formula captures the users response in a temporary variable called ComposeType and uses it to create a new report using the appropriate form.
ComposeType := @Prompt([OKCancelList]; "Report Type"; "Choose a report type."; "Adjustment Report";"Adjustment Report":"Infant Progress Report":"Toddler Progress Report":"Preschool Progress Report":"Transition to Kindergarten Report"); @Do(@Command([Compose]; ""; ComposeType));

Designing a form that lets users make selections from a view


You can design a form that uses @PickList to display a list of choices from a view. These steps assume you have already created a field, button, hotspot, or action to store the @PickList formula. 1. Open the form. 2. Choose View - Action Pane and double-click the action, or double-click the form and click the field, button, or hotspot. 3. In the Programmers pane, click Formula. 4. Write a formula using @PickList and the [Custom] parameter, unless you want to use [Name] to display a Domino directory or personal name and address book. 5. Close and save the form.
110 Application Development with Domino Designer

Using @PickList The @PickList function looks up the values in a view as @DbColumn does, but lets the user pick a value from one document. This is similar to using @Prompt in a form, but is specifically for use with views. @Picklist offers the following advantages over formulas that use @DbColumn or @DbLookup. It is not limited to 64K of data. It is faster than @DbColumn or @DbLookup. It allows users to type the first few characters of an entry to find it quickly in the view. For more information on the @Picklist function, see the Programming Guide. Example This formula displays the Products view of PROD.NSF in a dialog box:
choice:=@PickList([Custom] ; "":"prod.nsf" ; "Products" ; "Select a product" ; "Please select the products you want to order" ; 1 );

Designing a form for a Domino billing application


Domino billing is a server function that tracks server usage. Domino billing tracks only the documents that you specify. To specify the documents to track, you must add one or both of the following hidden fields to the form that creates the documents.
Field name $ChargeRead $ChargeWrite Result of adding this field to a form Domino creates a billing record when a user opens a document that contains this field Domino creates a billing record when a user creates, copies, edits, or saves a document that contains this field

To specify which documents to charge for 1. On the form that you want to track, create a field named $ChargeRead or $ChargeWrite. 2. 3. 4. 5. Set the field type to Number. Select Currency. On the Hide tab, hide the field for all options. Assign a cost value to the field. When users read from or write to documents that contains one of these fields, the billing task retrieves the cost value in this field and places it in a document billing record. 6. Save the form.
Chapter 5: Designing Forms 111

Note If there are many documents for which you want to charge, you can create a shared field and add it to multiple forms. If a database is updated by a template, you can modify the template to include the hidden fields. For more information on setting up billing, see Setting up billing in Administering the Domino System.

Customizing Form processed confirmation for the Web


After Web users submit a document, Domino responds with the default confirmation Form processed. To override the default response, add a computed text field to the form, name it $$Return, and use HTML as the computed value to create a customized confirmation.

Displaying a personalized response


The following $$Return formula returns the response Thank you, and appends the users name:
who:= @If(@Left(From; " ") = ""; From; @Left(From; " ")); @Return("<h2>Thank you, " + who + "</h2><br><h4> <a href=/register.nsf/Main+View?OpenView>Main View</a>");

Linking to another page


Include HTML with a URL to link to another page based on field values in the submitted document. The following $$Return formula returns a response based on the region the user selects. For example, if the user selects Europe, the message Visit our site in Italy displays with a link to the Web site in Italy. (Assume that stdAnswer and stdFooter are defined earlier in the formula.)
@If(Region="Asia"; stdAnswer + "<h2>Visit our site in <a href=\"http://www.japan.lotus.com\">Japan</a></h2>" + stdFooter; Region="Europe"; stdAnswer + "<h2>Visit our site in <a href=\"http://www.lotus.com\it_ciao/it_ciao.htm\">Italy</a> </h2>" + stdFooter; stdAnswer + stdFooter);

Returning another page


To jump to a different Web page, enclose a URL for the page in brackets. When the user submits the document, the Web client displays the referenced document. For example, the following $$Return formula displays the home page for the Lotus Japan site.
"[http://www.japan.lotus.com]"

112 Application Development with Domino Designer

Customizing search forms


You can customize Domain Search forms to meet the needs of your organization. The forms used for a Domain Search are Search Form, SeachResults, ResultEntry, and DetailedResultEntry, and they reside in the Catalog (R5.0) template. To customize the forms, create a database based on the template or copy and paste the forms into the domain catalog on the Domino server you are using for Domain Search. Refer to the following table if you are customizing a search form for use on the Web. The table lists the URL commands used on the Search Query form to drive the initial search through the SearchDomain URL. They are available on the results page for use by buttons and hotspots in the results form. For example, you may specify &SearchOrder=2 on your initial search form. The field SearchOrder will have a value of two in the results page. A Next button on the results form can use this value for the next page or override it by specifying something else. While TRUE and FALSE can be specified for some of the fields, when the values are carried over onto the results page they are 1 or 0.
URL Commands Query SearchMax SearchWv SearchOrder Description The search string Maximum number of entries to return in total; 0 = no limit Include word variants: TRUE or 1 or FALSE or 0 1 = by relevance 2 = by date ascending 3 = by date descending Default Value none none TRUE 1

SearchThesaurus Use thesaurus synonyms: TRUE or 1 or FALSE or FALSE 0 (This option is ignored by the R5 search engine) SearchFuzzy SearchEntry Start Count Scope Use fuzzy search: TRUE or 1 or FALSE or 0 Name of form to use for each result entry Start document for paged results; 0 = unpaged FALSE ResultEntry 0

Number to return for paged results; 0 = unpaged 0 Scope of search: 1 = notes databases only 2 = filesystem only 0 = both 0

If you are customizing a search form for use on in a Notes client, you will need to use the FTDomainSearch method. For more information about using the FTDomainSearch method, see the Programming Guide.
Chapter 5: Designing Forms 113

Customizing search results forms Search results are displayed using the SearchResults form, the ResultEntry, and the DetailedResultEntry form. The SearchResults form defines the layout of each page of results. The ResultEntry and DetailedResultEntry forms defines the format of a single result within that page, and is repeated for each result returned. On the Web you specify the name of this form through the SearchEntry field/argument. The fields below are for the ResultEntry and DetailedResultEntry forms.
Field Name DSCreationTime DSModifiedTime DSURL DSDBTitle DSDocSummary DSDocTitle DSDocAuthor DSScore DSSServer DSType Description Creation time of a document Modification time of a document URL to document Database title Document summary Document title Document author Relevance score Name of the server that the document was indexed on 0 indicates a Notes document, 1 indicates an external or file system document

You can name your results form whatever you want and then specify your chosen name in the SearchDomain URL or to the FTDomainSearch LotusScript call. The Web will look for a form named $$SearchDomainTemplate if you dont name one in the URL. How the SearchResults and ResultEntry/DetailedResultEntry forms are used. The LotusScript below is attached to the click event of the Search action hotspot used by the Notes client on the search form. The lines that call the name of the results form and the result entry form are underscored.
Sub Click(Source As Button) Dim s As New NotesSession Dim db As NotesDatabase Dim w As New NotesUIWorkspace Dim uidoc As NotesUIDocument Dim q As String Dim l As Integer Dim d As Integer Dim sort As String Dim stype As Integer 114 Application Development with Domino Designer

Dim useint As Integer Dim rtype As String Dim rformname As String Set db=s.CurrentDatabase Set uidoc = w.currentdocument uidoc.refresh Set doc=uidoc.Document q=doc.query(0) l=doc.resultlimit(0) d=doc.MaxDisplay(0) sort = doc.sort(0) usestr = doc.use sscope=doc.searchscope rtype=doc.GetItemValue("SearchType")(0) If rtype = "1" Then rformname="DetailedResultEntry" Else rformname="ResultEntry" End If Select Case sort Case "R" stype = FT_SCORES Case "O" stype = FT_DATE_ASC Case "N" stype = FT_DATE_DES End Select Forall values In usestr If values = "2" Then useint = useint + FT_STEMS If values = "3" Then useint = useint + FT_FUZZY End Forall Forall values In sscope If values = "1" Then useint = useint + FT_DATABASE If values = "2" Then useint = useint + FT_FILESYSTEM End Forall Chapter 5: Designing Forms 115

On Error Resume Next If db.isopen Then If Err <> 0 Then Messagebox STR_DBOPEN_ERROR Err = 0 Exit Sub End If Set srdoc = db.ftdomainsearch(q, l, stype,useint, 0,d,rformname) If Err <> 0 Then Messagebox STR_FTERROR_PREFIX & Error$, 0 , STR_ERROR Err=0 Exit Sub End If srdoc.Form="SearchResults" Call w.EditDocument(False, srdoc, True) End If End Sub

Tip You must select the Generate HTML for all fields option in the Form properties box to preserve field values when data is passed between a Web browser and the server. Using navigational buttons for paged results To make it possible to navigate forward and backward between pages of results, add buttons or hotspots to the SearchResults form. The fields available for use with next and previous buttons are listed in the table below. In the Notes client, the buttons should reinvoke the LotusScript FTDomainSearch function with revised arguments. On the Web they should be used to construct a new SearchDomain URL to fetch a new set of results.

116 Application Development with Domino Designer

Note If you use editable fields on a search result form, select the option Web Access: Use JavaScript when generating pages, in the Database properties. If selected, a URL attached to a hotspot or button will be computed on the click event. If it is not selected, the URL will be computed when the page is loaded.
Query Start Count Hits TotalHits SearchMax SearchWv (only for URL command) SearchOrder (only for URL command) SearchThesaurus (only for URL command) SearchFuzzy (only for URL command) SortOptions (only for Notes client) OtherOptions (only for Notes client) Search string used Starting document number Number of results requested for this page Actual number of results returned this page, may be less than Count Total number of hits found by the search Maximum number of entries to return in total; 0 = no limit Include word variants: 1 or 0 1 = by relevance 2 = by date ascending 3 = by date descending Use thesaurus synonyms: 1 or 0 Use fuzzy search: 1 or 0 FT_SCORES = by relevance FT_DATE_ASC = by date ascending FT_DATE_DES = by date descending FT_STEMS = Include word variants FT_FUZZY = Use fuzzy search FT_DATABASE = search databases FT_FILESYSTEM = search filesystems Name of the Result Entry form used Scope of search: 1 = notes databases only 2 = filesystem only 0 = both

SearchEntry Scope (only for URL command)

Chapter 5: Designing Forms 117

The fields in the table below are available for use with the Start and Count parameters and should be added to the results form as needed.
Field Hits TotalHits Description The actual number of hits returned. This field is useful in determining the Start parameter of Next. The total number of hits returned without regard to paging.

Tips for improving document display time


To help users create and read documents quickly, follow these guidelines when designing forms:

Designing forms
Avoid large bitmaps or graphics. Avoid the form property Automatically refresh fields. Instead, use the Refresh fields on keyword change for a choice field, or write a LotusScript field event to recalculate the document or update other fields when users move from a specific field. Avoid long tables with many computed fields.

Designing fields
Use @DbColumn or @DbLookup formulas sparingly, or replace them with LotusScript programs, which are generally faster and support error checking. Use simple formulas for hide when conditions. Avoid recalculating fields, if possible. Otherwise, change such fields to computed-when-composed fields, which calculate only when the document is composed but can be updated later if needed through buttons, actions, or agents. Use LotusScript form events rather than conditional formulas in the field itself to set field values. For example, to reset the status field if the document is being saved, create a script for a QuerySave event, rather than write a formula that uses @If(@IsDocBeingSaved;x;y). Minimize the number of fields, especially hidden fields, and use form events rather than field formulas to execute processing logic and avoid unnecessary recalculations. For example, suppose a form contains a hidden computed field called State, which determines where documents are in the workflow and
118 Application Development with Domino Designer

where they need to be sent. By replacing the field with a LotusScript program that sets a field value during the QuerySave form event, you can set the field value in the document only when it is saved, not when it is opened or refreshed. For more information on writing lookup formulas, or hide-when formulas, see the Programming Guide.

Testing a form before deploying it


There are two ways to test a form before using it in the actual application. You can preview the form from the Notes client or through a Web browser to see how it will look to a user and to make sure form elements are working. Alternatively, you can put the form through its paces, using it as users will. Testing the form in the application allows you to create documents, examine the documents through different views, and test all actions. For more information about previewing your work, see Previewing your design work.

Chapter 5: Designing Forms 119

Chapter 6 Designing Fields


This chapter describes how to create fields to collect and store specific types of information.

Fields
A field is the part of an application that collects data. You create fields on forms, subforms, or in layout regions. Each field stores a single type of information. A fields field type defines the kind of information a field accepts, such as text, numbers, dates, or names. When a user, either in a Notes client or a Web browser, creates a form, fills out the information in the fields, and saves the form, the data in the fields is stored in an individual document. The contents of the fields can then be displayed in documents and views or can be retrieved for use in formulas. A field can be used on a single form, or you can create shared fields for use in multiple forms in a database. When you create a field on a form, you define the following: Field name Field type Display options and field properties Computed or editable attribute Formulas or scripts associated with the field To create a field When you create a field on a form, the field displays with its name surrounded by a rectangle and a letter or symbol that lets you know what type of field it is. You can use tabs, returns, and other formatting tools to refine the fields position on the form. 1. Open the form. 2. Move the cursor where you want the field to appear. 3. Choose Create - Field.

121

4. On the Field Info tab of the Field Properties box: Assign a name to the field. Assign a field type. Select the display style. Select Editable or one of the computed options. 5. On the Control tab, select a display option for the field. 6. On the Fonts tab, format the font style for the field. Copying fields If you copy a field from one place on form to another, each copy of the field has a sequential number appended to its name to preserve name uniqueness. You can rename the field after copying it. If you copy a shared field, the new field changes to a single-use field. Deleting fields To delete a field, you select the field on the form and press the Delete key or choose Edit - Clear. Deleting a field from a form means that data for that field is no longer displayed in documents. The data still exists, however, and you can display it by adding a field with the same name to the form. To delete the field data, use the @DeleteField function to remove the field and its data from all documents containing the field. For example, to purge the AssignedTo field and its data from all Schedule documents, create an agent or action that uses the form name and @DeleteField: SELECT Form=Schedule; Field AssignedTo:=@DeleteField;

Creating a shared field


You can define a field for use on more than one form. For example, many forms have a creation date field, so you can define this field once and reuse it. When you define a field as a shared field, Designer displays the field with a dark border and adds the field name to a list of shared fields available for use in a database. Then to insert a shared field in another form in the database, you select the field name from the list of shared fields. You can design a field specifically as a shared field, or you can convert a single-use field that is not in a layout region to a shared field.

122 Application Development with Domino Designer

To create a shared field 1. Expand Resources in the Design pane and click on Shared fields. 2. Click the button New Shared Field. 3. Enter a name for the shared field. 4. Assign a field type and choose Editable or a computed option. 5. Close the properties box. To insert a shared field 1. Move the cursor where you want the field to appear on the form. 2. Choose Create - Insert Shared Field. 3. Select the shared field you want to use and click OK. 4. (Optional) Type a text label next to or above the field. 5. (Optional) Highlight the label and choose Text - Text Properties to change the text style.

Copying a shared field


To copy a shared field from another database, 1. Open the form you are copying the field from. 2. Select the field and choose Edit - Copy. 3. Open the form you want to paste the field in. 4. Move the cursor to where you want the field to appear on the form. 5. Choose Edit - Paste. Cutting and pasting converts a shared field to a single-use field. To turn the field into a shared field in the current database, select the field and choose Design - Share this field. Renaming shared fields Renaming a shared field affects all forms that use the field, as well as any documents created with the form. After renaming a shared field, edit each form that uses the shared field. Delete the old shared field, and insert the new shared field. Also revise all formulas that refer to the former field name. If you already used the form to create documents, create and run an agent to reassign field data to the new field name and to computed fields.

Deleting shared fields


To delete a shared field, you select the shared field from the list of shared fields and choose Edit - Clear. When you delete a shared field from a form, you delete only the field reference from the form. Because other forms may use the shared field
Chapter 6: Designing Fields 123

definition, its definition remains in the database. Unless you delete the field data with the @DeleteField function, the data from deleted shared fields can be displayed again by adding a field of the same name or re-inserting the shared field. When users open a document that refers to a deleted shared field, they see this message:
Cannot locate field definition for Field: <field name>.

When users click OK, they see the contents of the shared field as non-editable text. To prevent this message, modify each form to convert the old shared field to a single-use field (by cutting it and pasting it back on the form). The field definition is stored within each form, rather than in a central location, and documents can be displayed as they were when they referred to a shared field definition.

Converting a single-use field to a shared field


1. Open the form. 2. Click the field to be shared. 3. Choose Design - Share This Field. To change a fields status from shared to single-use, click the field and choose Edit - Cut and Edit - Paste. You cannot convert fields in a layout region.

Field names and labels


A field name is a required element. You assign a field name in the Field Properties box when you create the field. A field label is descriptive text you create that appears next to or on top of the field on the form, and helps the user understand the field. Label text might name a field for example: To, From, Author, Subject, or Date. Or it might describe a user action for example, Enter a product name.

Naming a field
A field name must begin with a letter and can include letters, numbers, and the symbols _ and $. The name can contain up to 32 bytes. (If youre using multibyte characters, remember that 32 bytes is different than 32 characters). Use short, descriptive field names that you will remember when you write formulas that refer to the fields.

124 Application Development with Domino Designer

Field names cannot contain spaces. Run multiple words together, for example, ModifiedDate, or separate them with an underscore: Modified_Date. The Designer templates use the naming convention of an initial capital letter followed by lowercase letters, for example, SendCopyTo. If several fields on forms in a database contain similar information, for example, the date of creation and the authors name, use the same field name for all of them. This makes sharing information between forms easier as you continue to develop the application. Establishing and maintaining naming standards simplifies application design throughout your organization. Renaming a field Unlike forms and views that can have aliases, a field can have only one name. Renaming a field has the same effect as deleting a field from a form. For example, if you have a field called Comments, and users enter text into many instances of this field in documents, and you then rename the field to Observations, all of the data in Comments will no longer appear when you display the document. If you must rename a field and need to transfer data, create a new field, create and run an agent to reassign data to the new field, then delete the old field. Remember to update all formulas to refer to the new field name.

Defining field types


The fields field type determines what type of information it can contain. You define the field type in the Field Properties box. The field types are: Text Date/Time Number Dialog List Checkbox Radio button Listbox Combobox Rich text Authors Names

Chapter 6: Designing Fields 125

Readers Password Formula

Text and rich text fields


To collect, store, and display text in a field, create a text field or a rich text field. Text fields generally suffice for data entry or text output in an application, while rich-text fields are better for formatted text, large amounts of text, or embedding or attaching objects. For example, the Subject field on a mail form is a text field, and the Body field is a rich text field. A rich text field can be used anywhere except in a layout region. A rich text field is not subject to the size limitations imposed on other field types.

Displaying graphics, attachments, and objects in a rich text field


Many databases use an editable, rich-text field named Body to give users the flexibility of adding whatever they want to the main part of a document attachments, graphics, objects, or different fonts and colors. A rich text field can contain anything a page contains. You can use a rich-text field to launch an OLE object that is, to open an object from another application within a form. You can even define the field so that an OLE object automatically launches when a user opens the form. For more information, see Launching objects automatically.

Rich text fields on the Web


You have two options for defining how a rich text field displays on the Web: The rich text field displays for editing within an HTML text area. This is the default behavior. The rich text field displays using the editor applet, allowing for a broader range of editing options.

Using the editor applet


Web users can do the following when using the editor applet in a rich text field: Bold, underline, and italicize text Change to Helvetica, Courier, or Times (fonts supported by the Java Development Kit (JDK), Release 1.0.2) Change font size Change font color
126 Application Development with Domino Designer

Align paragraphs (left, center, right) Indent paragraphs Use bulleted and numbered lists Create links Cut, copy, and paste text within the rich text field Note Web users cannot paste text from outside the editor because of the limitations of the JDK, Release 1.0.2. Enter international characters Note Not all international characters can be displayed in the editor applet. The ability to display international characters depends on the fonts installed on the users workstation and the version of the browser the user is working with. Most characters entered in the editor will be correctly transferred to Domino (depending on the browser).

Enabling the editor applet


You can enable the editor applet in rich text fields only. To enable the editor applet: 1. Create or select a rich text field. 2. Choose Design - Field Properties. 3. On the Field Info tab, in the Web Access section, select Using Java Applet. When the editor becomes active, it displays as large as the Web browsers window. It is recommended that you resize it. The minimum size recommended is 300 by 500 pixels. To resize it: 4. In the Objects tab of the Info List in the Programmers pane, select the rich text field. 5. Click HTML Body Attributes. 6. In the Script area, enter the height and width. For example:
"HEIGHT=300 WIDTH=500"

If the same document is edited by both a Web browser and a Notes client, there are some additional caveats. For example, it is possible to format a document in the Notes client using a formatting feature that is not supported in the editor applet. Also, there are features that, once opened and edited in the editor applet, will subsequently not format properly if opened for editing in the Notes client. These are the formatting features to avoid if editing a document with both the Notes client and a Web browser: First line indent or outdent Full justification paragraph alignment
Chapter 6: Designing Fields 127

Tabs Images Ordered lists Tables In addition, any features that the editor applet cannot interpret are displayed as HTML in green on the document.

Number fields
Use Number fields for numeric and currency data. The Number field type lets you limit a field to numerical values and define how the numbers display in a form. For example, a Monthly Total field in a Budget form adds together all of the numeric values from the fields listed in the following formula to arrive at a total budget figure:
Advertising + Entertainment + Miscellaneous + Overhead + Salaries + Travel

If you dont want users to change the value of a numeric field, select a Computed option in the Field Properties box. In the example above, the Monthly Total field is computed so users cannot edit the value. Fields used in calculations must have default values. Otherwise, the message Incorrect data type for operator or @Function: Text expected appears. On the Control tab of the Field Properties box, you can specify whether the field should display formats according to the custom settings you specify, or whether it should use the default settings of the users workstation. In the case of currency, where you might want different fields to display different currency formats, you can apply settings on a field level. When you are defining a currency field, you can choose a currency symbol from an extensive list. If the symbol you need is not included in the list, you can create a custom currency symbol by pasting in the ASCII character for the currency symbol and entering the corresponding country code. Caution Applying different currency formats, such as displaying British pounds in one field and American dollars in another, might result in unexpected results if you combine values using the formula language or a scripting language.

128 Application Development with Domino Designer

Choose any of these number formats on the Control tab of the Field Properties box: Decimal displays numbers either as they are entered (zeroes to the right of the decimal point are suppressed), or with a fixed number of decimal places, depending on what you specify. To base the decimal symbol and thousands separator display on the type of measurement (Imperial or Metric) users set in the operating systems International User Preferences, choose Client. To set the decimal symbol and thousands separator yourself, choose Custom. Note A number field can store up to 8 non-zero decimal digits without loss of precision. Notes implements floating point arithmetic using the IEEE64 industry standard. In cases where a user enters more than 8 non-zero decimal digits, rounding may occur and the number may display and be stored differently from the number the user entered. Percent displays a number as a percentage. For example, 12 displays as 1200%, while .12 displays as 12%. Scientific displays numbers using exponential notation. For example, 10,000 displays as 1.00E+04. Select the number of decimal places from the Decimal Places list. Currency displays values with the currency symbol you specify. The default is the American dollar sign. For example, $15.00 is displayed when the value is 15 and 2 is selected in the Decimal Places list. You can select a different currency symbol from the list, or enter a custom currency symbol and country code. Designer recognizes the following formats for numbers: Integers Decimal fractions Scientific notation Currency 123, -123 1.23, 0.12, -.12 1.23E2, -1.23E12 $2.50, ($600.09)

Notes can store numbers from 2.225E-308 to 1.798E308 with 14-digit accuracy.

Date/Time fields
Date/Time fields display time and date information in a variety of formats. You can define a date or time field as editable by the user, or you can choose a computed option so the user cannot change the field value. Dates may range from 1/1/0001 through 12/31/9999. Entering two-digit years between 00 and 49 assumes the century starting in the year 2000. Entering two-digit years between 50 and 99 assumes the century starting in the year 1900. If you want users to enter a four-digit year in the field, on the
Chapter 6: Designing Fields 129

Control tab of the Field Properties box, select On input Require user to enter four digit years. Times may range from 00:00:00:00 through 23:59:59:59 in the 24-hour format and from 12:00:00 AM through 11:59:59 PM in the 12-hour format. Choosing a Date/Time format On the Control tab of the Field properties box you can select the format for the display of the Date/Time field. You can choose to use the date/time display based on users workstation preferences, or you can customize the display. To display a date 1. Select or create a Date/Time field. 2. On the Control tab, select Display Date. Select Users settings to use the preferences from the users workstations. Select Custom to customize the display. If you select Custom, choose display options. As you select options, the sample will change to show you what the user will see. Note If you specify a comma as a date separator (for example: 11,15,98) then you must use a semi-colon if you are separating multiple dates in a list (for example: 11,15,98; 12,15,98; 1,15,99). If you specify a semi-colon as the date separator, then you must use a comma to separate multiple values in the list. The following are the date display options: Show: All Only month, day, and year Only weekday, month, and day Only month and year Only month and day Only year Special: None Show today when appropriate. Always show four digit year. Show four digit year for the 21st century Show year only when not this year
130 Application Development with Domino Designer

Format: YMDW - Year, month, day, weekday. For example, 98 12/17/Thu. WMDY - Weekday, month, day, year. For example, Thu 12/17/98. WDMY - Weekday, day, month, year. For example, Thu 17/12/98. To display a time 1. Select or create a Date/Time field. 2. On the Control tab select Display Time. Select Client to use the preferences from the users workstations. Select Custom to customize the display. If you select Custom, choose display options. As you select options, the sample will change to show you what the user will see. The following are the time display options: Show: All Hours, minutes, and seconds Hours and minutes Hours only Format: 12 hour 24 hour To show both date and time together in the same field select both Display Date and Display Time. Time zone options Choose any of these time zone options on the Control tab of the Field Properties box: Adjust time to local zone - Displays the time relative to the time zone in which the document was created. For example, if the document was created at 3:00 PM in Boston and is read by a user in Los Angeles, the creation time is adjusted to the Pacific U.S. time zone and displays as 12:00 PM. Note In order to take advantage of time zone conversion, the date must be included in the field. Always show time zone - Displays the zone in which the document was created as a part of the value. In this case, the time itself is not adjusted for the readers time zone; instead, Notes displays the creators time zone. For example, if the
Chapter 6: Designing Fields 131

document was created in Boston at 3:00 PM, the user in Los Angeles sees the creation time as 3:00 PM EST. Show only if zone not local - Displays the zone in which the document was created only if the document was created in a different time zone than it is being viewed in. For example, if the document was created in Boston at 3:00 PM, users in the U.S. Eastern standard time zone see the creation date as 3:00 PM, while users in other time zones see the creation date as 3:00 PM EST. Note In order to take advantage of time zone options, the date must be included in the field. Examples: Possible date/time formats 10/30 10/30/95 10/30/1995 Monday 10/30/95 Monday 10/30/1995 October 30, 1995 Monday October 30, 1995 Today Yesterday Tomorrow Monday Tuesday Wednesday Thursday Friday Saturday Sunday 10/30 11:00 PM 10/30/95 11:45:30 AM 10/30/1995 11:45:30 AM Monday 10/30/1995 11:45:30 AM

132 Application Development with Domino Designer

Monday 10/30/1995 11:45:30:00 AM Monday 10/30/1995 11:45:30:00 AM EST Monday October 30, 1995 11:45:30:00 AM EST Monday 11:45:30:59 AM 11:00 PM 11:45:30 AM 11:45:30:59 AM 11:45:30:59 AM Today 11:45:30:59 AM EST Today 98 12/17/Thu

Formulas for Date/Time fields


Dates and times are often calculated by formula rather than supplied by a user. Use the following @functions to create date and time field values.
To display Create a Date/Time field showing Date and time Date Date and time Use the formula @created @modified @today @now

Date a document is created Date and time Date a document is modified Current date Current date and time

Creating a graphical display for Date/Time fields


You can display certain editable Date/Time fields either as a blank field that users type a date or time into or as a graphical date/time control. Note Graphical date/time controls are not supported on the Web.

Chapter 6: Designing Fields 133

To create a calendar pop-up control Users can click a helper button on the field box to bring up a one-month calendar on which they can select the date they want.

1. Create an editable Date/Time field. 2. On the Field Info tab of the Field Properties box, select Native OS style. 3. On the Control tab, choose: Display Date Users settings or Custom display For Custom display, choose display options. To create a time control Users can select time by clicking on the control and sliding the selection bar to a new time.

1. Create an editable Date/Time field. 2. On the Field Info tab of the Field Properties box, select Native OS style. 3. On the Control tab, choose: Display Time Users settings or Custom display
134 Application Development with Domino Designer

For Custom display, choose display options. To create a duration control Users can select a range of time with a duration control, for example, from 12:00pm - 1:00pm.

1. Create an editable Date/Time field. 2. On the Field Info tab of the Field Properties box, select Native OS style and Allow Multi-Values. 3. On the Control tab, choose: Display Date Users settings or Custom display For Custom display, choose display options. Examples: Creating a field to display dates and times Tracking modification dates You want to track the dates on which purchase requisitions are created and modified. On the Purchase Requisition form, you create a computedwhen-composed Time field called CreationDate with the formula @Created. This date always shows the date the author first saves the document. To track editing dates, you also created a computed Time field called ModifiedDate with the formula @Modified. This date is the same as the CreationDate the first time the document is saved but is updated automatically each time the document is modified. Determining the daily age of a document In your Service Tracking database, you want to track the age of request documents. On the Request form, you create three fields to calculate the information.

Chapter 6: Designing Fields 135

The first field is a computed Time field called DateCreated containing this formula:
@Created

The second field is a Time field named CurrentDate containing this formula:
@Now

The third field is a computed Numbers field that is calculated by this formula, which uses the values from the previous two fields:
@Abs(@Integer((CurrentDate - DateCreated) / (60 * 60 * 24)))

Notes stores dates as a number of seconds, so that number is converted to days by dividing it by (seconds per minute [60]) * (minutes per hour [60]) * (hours per day [24]).

Names fields
Create a Names field to display user names. A names field can be computed or editable. If you associate the formula @UserName to a Names field, the name will appear the way it appears in Notes IDs for example, Sara Ryan/Acme/US. To display only the common name portion of names, use the [CN] parameters with @Name. For example, in an editable names field called Members use this formula as the default value:
@Name([CN];Members)

This formula displays the name Sara Ryan if the users hierarchical name is Sara Ryan/Acme/US For more information about formulas for displaying user names, see the Programming Guide.

Looking up names for field values


To help users enter names correctly in a document, provide links to existing lists of names. For example, a Names field might require that users select names from the access control list for the database. This enables users to pick a name from a list, eliminates spelling errors, and restricts names in the field. Other sources for names are the Domino Directory or a view dialog that presents names from a column in a view. Lookup options are available on the Control tab of the Field Properties box when you create a Names field, an Authors field, and a Readers field. You can turn off this option by maintaining the default choice of none. If you

136 Application Development with Domino Designer

select a lookup option for the field, users press CTRL + ENTER or click the entry helper button to the right of the field to see a list of possible entries. Lookup options are not supported on the Web. Lookup options Use Address dialog for choices - This option displays the Names dialog box so users can select names from a Personal Address Book or Domino Directory. Select Look up names as each character is entered to help users fill in a name quickly. Notes looks up a match for the typed letters in the open Address Book or directory. Use Access Control List for choices - This option brings up a list of people, servers, groups, and roles in the access control list. Use View dialog for choices - This option brings up a dialog box containing entries from a column in a database view. Select the database to look up, select a view, and select a column number. For information on the access control list for a database, see Managing Domino Databases.

Readers and Authors fields


Reader and Authors fields allow you to control who can read and create documents created from a form. Because these fields work with the overall Designer security model, they are described in Restricting Access to and Securing Parts of an Application.

Creating fields to display lists of choices


You can create fields that present users with a list of choices. The list can be generated by formula, entered manually by you, or created or added to by users who enter values. Enter lists and formulas for choice fields on the Control tab of the Field Properties box. If available for the interface style, you can select Allow values not in list on the Control tab of the Field Properties box to let users add their own words without changing the original list. Also, some of the interface styles have an option to Allow multi-values on the Field Info tab which lets users select several choices in the field. Choice list fields can be editable or computed; however, most choice list fields are editable. The field types that present lists of choices are:

Chapter 6: Designing Fields 137

Field Type

Usage

Allow values Allow not in this list multi-values Available

Available Dialog list Users either press ENTER or click the entry helper button to see all the choices at once, press the space bar to display choices one at a time, or type a letter to display the first choice beginning with that letter. Select Display entry helper button if you do not want to display a button next to the field that a user clicks to view all the choices. Dialog lists are not available in layout regions. Not available Checkbox Each choice is displayed with a box users click to select. Checkboxes have border and column options. To create a wide checkbox panel, choose a column number between 2 and 8. Radio button Each choice is displayed with a button; users can click only one. Radio buttons have border and column properties. To create a wide button panel, choose a column number between 2 and 8. Not available

Available

Not available

Not available List box Each choice is displayed with an expanded list box. Users click an entry to select it. List boxes have border, size, and placement options. To resize the list box without dragging it, change the Width and Height measurements. To move the list box in a layout region without dragging it, change the Left and Top measurements. Available Combo box Each choice is displayed with a drop-down list box. Users click the drop-down arrow to see the entries and click the one they want. Combo boxes have border, width, and placement options. To resize the combo box without dragging it, change the Width measurements. To move the combo box in the layout region without dragging it, change the Left and Top measurements.

Available

Not available

138 Application Development with Domino Designer

Generating choices for lists


When you are defining a list field, choose one of these options on the Control tab of the Field Properties box for generating the list. Enter choices (one per line) Type a list of choices in the edit box. Select Sort to display the list in alphanumeric order. Click the green check mark to save your entries. Choices can contain letters, numbers, and all punctuation characters except commas. Type a formula in the formula window to generate a list of choices. Click the green check mark to save your entries.

Use formula for choices

Use Address dialog This option displays the Names dialog box so users for choices can select names from a Personal Address Book or Domino Directory. Click Look up names as each character is entered to help users fill in a name quickly. Notes looks up a match for the typed letters in the open Address Book or directory. Use Access Control This option brings up a list of people, servers, groups, list for choices and roles in the access control list for the database. Use View dialog for This option brings up a dialog box containing entries choices from a column in a view. Select the database to look up, select a view, and select a column number. Use View dialog for choices Looking up values in a view lets you retrieve data from databases. This is convenient for displaying choices that change, such as customer names, sales territories, and job titles. View lookups provide the following benefits: Non-designers can maintain choices without having access to the rest of the database design. Designers can avoid hard-coding choices into fields. This makes verification and maintenance easier. Designers can hide the design of the database without affecting maintenance of choices. Designers or administrators can customize the application or conveniently translate lookup information to other languages. Users can review choices and codes more conveniently from outside the form or application.

Chapter 6: Designing Fields 139

Note Use lookups sparingly because they adversely affect the performance of the application. To retrieve information from Domino or non-Domino databases you can use @DbColumn and @DbLookup formulas instead of using a View dialog lookup. For more information on @DbColumn and @DbLookup, see the Programming Guide. Examples: Creating a field to display a list of choices You want to make it easy for users to include a product number when they fill out a Purchase Request. Create an editable Dialog List field named ProductNumber and use the Use View Dialog for choices property to generate choices. You select the Inventory Database, the By Product Number view, and Column 1, where product numbers are listed. Creating a formula-generated list A Travel Request form contains an editable Listbox field called Country that uses the following formula to show only those countries relevant to the location selected by the user:
@If(Location="Europe";"France":"Germany":"Italy":"Spain"; Location="Far East";"Japan":"Singapore":"South Korea";Location="North America";"Canada":"Mexico":"United States";"")

Creating aliases for choices in a list


You can create aliases for choices, so that if the word itself changes, any formula referencing the field still works. You can also create short aliases for long words to keep formulas more concise. Aliases are also useful if your application is to be translated, since only the choices themselves need to be translated and formulas dont need to be rewritten. Enter the alias using | (a vertical bar) followed by the alias. For example, A is the alias for All in this entry:
All | A

If you use aliases, the leftmost name is displayed in the document, but the rightmost name is stored internally.

140 Application Development with Domino Designer

Converting aliases to full category names


If you are creating a view with a categorized column that refers to choice list fields, you need to be aware that the view will use the alias name as the category rather than the value that users see in documents. For example, a field named RequestType contains the following choices:
Hardware Request | HW Software Request | SW Service Request | SVC

In a categorized view, the categories display as:


HW SW SVC

This can be confusing to users. To display the full names as category names, you must use a hidden field or column formula that converts the aliases back to their full names. For example, the following is a column formula for the view to convert the alias back to their full names for display in the categorized column:
@If(RequestType="HW";"Hardware Request";RequestType="SW"; "Software Request";"Service Request");

Example: Using aliases for choices in a list You want Service Repair Requests to have a field for product groups. Create an editable dialog list field called Product and on the Control tab, select Enter choices (one per line). Include aliases, so that if the product groups change, any formula referencing the alias still works. Enter this list: Microwaves | 1 Ovens | 2 Refrigerators | 3 Specialty Items | 4 Toasters | 5

Chapter 6: Designing Fields 141

Columns that refer to list fields use the alias names in the view, not the word seen by users in the document. To display the contents of the Product field in a view, you need to use a hidden field or column formula that converts the alias name to its long form:
@If(Product="1";"Microwaves";Product="2";"Ovens";Product="3"; "Refrigerators";Product="4";"Specialty Items";Product="5";"Toasters";Product="";"";"");

Password fields
A Password field is a text field that maintains a users privacy by displaying each character a user enters as an asterisk on the screen. The contents of the Password field is not secure, and it is visible in the Document Properties box from the Notes client. There are several ways to secure the contents of a Password field. If you are using the Password field as a method for securing an application, the best way to secure the contents of a Password field is not to save the contents after the entry is verified. This can be done using a formula that clears the field once its been verified. You can use the input translation event or a LotusScript QuerySave event. Example: Using an input translation formula This formula is an input translation formula for a Password field. When the user enters a password, Domino looks up the user in the Domino Directory and gets the users HTTPPassword field. Then, it compares the value that the user inputs into the field with the HTTPPassword field. If the values match, it presents a prompt saying You passed. If the values do not match the prompt says You entered an incorrect password.
x:=@DbLookup("";"Server/Acme":"names.nsf";"($Users)"; @Username;"HTTPPassword"); REM REM REM REM "This compares the value above to the value the user entered after running it through the @Password hash function and prompts the user whether they typed in a valid password or not.";

@if(@isError(x);@Prompt([OK];"Error";"Error");@Password(Passwo rd) = x;@Prompt([OK];"You passed";"You passed");@Prompt([ok];"Password failure";"You entered an incorrect password")); REM "This deletes the password field."; @Unavailable

142 Application Development with Domino Designer

Example 1: Using a QuerySave event This script determines whether the password field contains a password. If it does it gets the name of the author of the document and puts the abbreviated form of the name into the PublicEncryptionKeys field. This effectively encrypts the Password field with the authors public key. This does not involve a lookup to the Domino Directory to get the key. It is retrieved from the users ID file.
Dim doc As NotesDocument Dim db As NotesDatabase Dim session As New NotesSession Set db = session.CurrentDatabase Set uidoc=Source Set doc=source.Document If doc.GetItemValue("Password")(0) <> "" Then Set PkName = New NotesName(doc.GetItemValue("Author")(0)) Call doc.ReplaceItemValue("PublicEncryptionKeys", PkName.Abbreviated ) End If

Example 2: Using a QuerySave event This script determines whether one or more Password fields contains a password. If one of the fields does contain a password, the script gets the values from the Author field and the OtherEditors field (which might contain a group) and expands the OtherEditors field so that it has names and puts the abbreviated form of the name into the PublicEncryptionKeys field. This effectively encrypts the Password field with the public keys for all unique entries in the two fields. This does involve a lookup to the Domino Directory to get the keys for each of the users listed, unless the only value is the name of the current user. If there is more than one name to look up, then it finds the public keys from the Domino Directory. If the only key to look up is the authors, it is retrieved from the users ID file.
Dim s As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument Set db = s.CurrentDatabase Dim uidoc As notesuidocument

Chapter 6: Designing Fields 143

Set uidoc=source Set doc = uidoc.document

If (doc.GetItemValue("Password1")(0) <> "") Or (doc.GetItemValue("Password2")(0) <> "") Then Call doc.ReplaceItemValue("PublicEncryptionKeys",Evaluate(|@Name([A bbreviate];@Unique(Author:OtherEditors))|,doc)) End If

Formula fields
Formula fields are used to populate a subscription list, which works in conjunction with the Headlines.nsf database. The Headlines database is accessible from the Bookmark pane of the Notes client and can be used as the home page of a Notes client. The Headlines database includes a feature called subscriptions. Each database designer has the option of including a subscription form in a database. When a user subscribes to a database (by filling out and saving a subscription form in that database), it triggers a server task that will notify the user whenever a document of interest is saved in that particular database. The criteria that the server looks for is contained in a formula field on the subscription form. Although users fill out the subscription form in the database they want to subscribe to, the subscription documents are stored in users headlines databases on their local client. You can use the default subscription form, which is located in the headlines.ntf database. To use the default form, copy and paste it into your database. The subscription form, named $Subscription, is in the Headlines.nsf or Headlines.ntf database that is included with Designer. You can use the subscription form as is or you can customize it. If you customize it you must include the formula field. The formula field on the $Subcription form is named $HLFormula and is on the second tab of the tabbed table on the right side of the form. The $HLFormula field is a computed field. If you choose to keep the formula field computed, you write a formula that resolves to a formula for a subscription list. A formula field must resolve to a formula in order for the server to be able to retrieve the subscription criteria for the user. Another option for the formula field is to choose Literalize fields on the Field Info tab of the Field Property box. When you select the Literalize fields option, you are programming the formula field to accept the formula you put in without compiling it. If you literalize a formula, the field references must be: text, text list, number, number list, date, date range, or
144 Application Development with Domino Designer

date list. If the field referenced is of any other field type, it will be left out as a field reference. The following is an example of a formula for a formula field for which Literalize is selected as an option:
Select (Names = ExampleNames) & (Numbers = ExampleNumbers) & (Categories = ExampleCategories)& (Dates = ExampleDates)

If the current document has these fields and values:


Field ExampleNames ExampleNumbers ExampleCategories ExampleDates Value CN=Sara Ryan/O=Acme : CN=Jack Town/O=Acme 1: 2: 3 Arizona : Florida : New York [3/26/82]:[10/08/86]:[5/30/98]

Then the formula field will literalize to:


Select (Names = "Sara Ryan/Acme" : "Jack Town/Acme" ) & (Numbers = 1 : 2 : 3) & (Categories = "Arizona" : "Florida" : "New York") & (Dates=[3/26/82]:[10/08/86]:[5/30/98]

If you choose the computed option, the formula you enter must resolve to another formula. This provides the ability to optimize complicated formulas before they are saved. After the formula is evaluated, the resulting formula is saved. If the resulting formula is invalid, the field is saved with a value of type error. In some cases, the user would never be able to exit out of the document. To differentiate between success and failure, you should test in the QuerySave event to determine if the Formula field is indeed a formula. If it is not, then the computation did not result in a valid formula. For example, a computed formula field has the following formula:
tLitNames := "\"" + @Implode( ExampleNames; "\" : \"") + "\""; tLitNumbers := @Implode( @Text(ExampleNumbers); " : "); tLitCategories := "\"" + @Implode( ExampleCategories; "\" : \"") + "\""; "Select (Names = " + tLitNames + ") & (Numbers = " + tLitNumbers + ") & (Categories = " + tLitCategories + ")"

Chapter 6: Designing Fields 145

If the current document has these fields and values:


Field ExampleNames ExampleNumbers ExampleCategories Value CN=Sara Ryan/O=Acme : CN=Jack Town/O=Acme 1: 2: 3 Arizona : Florida : New York

Then the formula will compile to:


Select (Names = "Sara Ryan/Acme" : "Jack Town/Acme" ) & (Numbers = 1 : 2 : 3) &(Categories = "Arizona" : "Florida" : "New York")

Editable and computed fields


You choose whether a field is editable or computed in the field properties box, when you create the field. If a field is editable, a user can enter or change the value of the field. If a field is computed, a formula calculates the field value. Users cant change the values in a computed field. Number, date/time, authors, readers, and names fields are usually computed. Text, rich text, and choice list fields are usually editable.

Writing field formulas


You enter field formulas in the Script area of the Programmers pane. First, choose the event for which you are providing the formula from the Object tab of the Info List. For example, the default value event provides an initial value for an editable field. If you include a Date field on a form, you might want to enter a default value formula of @Today. This populates the field with todays date. Use the Reference tab on the Info List of the Programmers pane to access the list of fields, @commands, and @functions. You can use the Reference list as a shortcut for looking up @functions and @commands and for pasting them into the formula. For information on writing formulas for fields, see the Programming Guide.

Computed field formulas


Computed fields are used to automatically enter data, such as the authors name or the date, in a field. You can have more than one computed field on a form. Computed fields require formulas to supply their values. For example, you use a computed field to assign a creation date to a document. Computed fields are normally recalculated when users create documents, choose View - Refresh Fields, press F9, or save documents. Selecting the
146 Application Development with Domino Designer

field property Compute after validation is useful when a field is dependent on values in other fields and you want to be sure that the calculation occurs after those fields have been validated. When its important for users to see results as they proceed, you can force each field to be calculated as its filled in by selecting the form property Automatically refresh fields. This is useful when fields at the bottom of the form are dependent on field values at the top. Be aware that this property can slow down document display time if the form has many computed fields. There are three types of computed fields:
Type of computed field Computed Computed when composed Formula calculates A computed field formula calculates each time a user creates, saves, or refreshes a document. A computed-when-composed field formula calculates only once: when the user first creates the document. Use this type of formula in a field to preserve information about the origin of a document, such as the creation date or original author, or to create a field whose original value never changes, such as a document sequence number. A computed-for-display field formula recalculates each time a user opens a document. Use this type of formula in a field to display information that is relevant only to the immediate session, such as the current time or the results of calculations that you dont need to save. The field value exists during the current session only and is not stored. You cannot display the contents of a computed-fordisplay field in a view.

Computed for display

To create a formula for the value of a computed field 1. Select any type of computed field. 2. Select Value from the Objects tab of the Info list. 3. Write a formula, a field name, or a text string in quotation marks in the Script area of the Programmers pane. 4. Click the green check mark to verify and save the formula. 5. (Optional, for computed or computed-when-displayed fields) To delay computing until after validation formulas run, choose Design - Field Properties and select Compute after validation on the Field Info tab. 6. (Optional) To recalculate field values while users edit a document, click the form and choose Design - Form Properties, click the Form Info tab, and select Automatically refresh fields.

Chapter 6: Designing Fields 147

Note Automatically refreshing fields can slow down document display time. A faster alternative is to write a LotusScript field event to recalculate the document or update other fields when users move from a specific field. For information on writing formulas for fields, see the Programming Guide.

Editable field formulas


You can write up to three formulas for each editable field: The default value formula provides an initial value that the user can change. Providing a default value for an editable field ensures that the field gets filled in and often removes the need for users to enter data such as their name or the date. The input translation formula modifies the contents of a field after a user fills it in for example, to correct typing or standardize the format. Use an input translation formula to format information entered by users for example, to make all entries uppercase. The result of the formula replaces what the user entered. Input translation formulas are evaluated each time a document is saved, recalculated, or refreshed. The input validation formula checks the contents of a field against predefined criteria, making sure the entry meets certain requirements. For example, use an input validation formula to ensure that users fill in a required field. Input validation formulas are evaluated each time a document is saved, recalculated, or refreshed. To create a default value or input translation formula 1. Create an editable field. 2. Select Default Value or Input translation from the Object tab of the Info List. 3. Write one of the following in the Script area of the Programmers pane: a formula a field name a text string in quotation marks 4. Click the green check mark to verify and save the formula. To enter a literal text string, enclose it in quotation marks ( ). Field names dont need quotation marks. If you select the form property On Create: Formulas inherit values from selected document when designing the form, use the default formula to specify the field from which this new field inherits its value. When a new

148 Application Development with Domino Designer

document is composed with this form, the field value is copied from the document that is currently highlighted if that document contains the specified field. An alternative to an input translation formula is to write a script for the Exiting event that verifies information. To create an input validation formula 1. Create an editable field. 2. Select the Input Validation event from the Objects tab of the Info List. 3. Write a formula in the Script area of the Programmers pane using @Failure and @Success. 4. Click the check mark to save the formula. @Failure prevents the user from saving the document until the user enters a value that meets the criteria. As part of the formula, include text that clearly indicates what is wrong and how the user can correct it. For information on writing formulas for fields, see the Programming Guide. Examples: Creating a formula for an editable field Default value formula examples The default value formula provides an initial value for an editable field. You can set the value to a specific number or text string, or you can use a formula. For example:
The formula 0 @Now @Name([CN];@Username) Price Returns The number 0 The current time and date The common name portion of a users hierarchical name The value of the field named Price

Connecticut:New York:New Jersey A text list containing Connecticut, New York, New Jersey Product + , + Department The value of the field named Product, followed by a comma and a space, and the value of the field named Department

Chapter 6: Designing Fields 149

Example: Input translation formula The following formula translates the text in the Attorney field for display with initial capital letters. If a user enters the text john smith in the Attorney field, it is translated to John Smith when the document is saved.
@ProperCase(Attorney);

The following formula gives documents a uniform look by capitalizing the initial letter of the value in the Subject field and removing extra spaces.
@Trim(@ProperCase(Subject));

Input validation formula examples


Field criteria User must enter a value that is less than 100 in Cost field Formula @If(Cost<100;@Success;@Failure(Cost must be less than $100.));

User must enter a value for @If(Subject = ; @Failure(You must enter a subject the Subject field for your document.); @Success)

Examples: Calculating a value for a computed field Combining text and field values to create a message The SchedDisp field, which displays only when users read or print a document, can display two different messages depending on the value in the Sched field. If it is a special, temporary schedule, the message combines words with a text-based version of the value in the Date field. If the schedule is permanent, the message is Regular schedule.
@If(Sched = "Special schedule"; "Special schedule for week starting: " + @Text(Date); "Regular schedule")

Totaling monthly budget figures The MonthlyTotal field in the Budget form is a computed Numbers field that is formatted for Currency with two decimal places. The formula totals the values in each category to calculate the total budget.
Advertising + Entertainment + Miscellaneous + Overhead + Salaries + Travel

Storing the date and time a document is created Notes automatically uses internal fields to store the date and time a document is created. To display this information, define a Time field that is computed-when-displayed, and then write this formula for it:
@Created;

150 Application Development with Domino Designer

The field is defined as computed-when-displayed, rather than computed, to avoid storing the creation date information twice. Determining the normal work day age of a document This field formula determines the age of a document in work days, based on a five-day work week. In the following example: DateCreated is a field containing the date when the document was created. The fields data type is Date/Time, and it is computed using the formula @Created. Currentdate is a field containing the current date of the document. The field data type is Date/Time, and it is computed using the formula @Now. Because Notes sorts dates in seconds, you must divide by (seconds per minute) * (minutes per hour) * (hours in a day), which equals 86400. Weekend_days is a temporary variable that contains Age of document in days divided by Number of days in a week, multiplied by Days in a weekend.
temp := (@Date(Currentdate) - @Date(DateCreated)) / 86400; weekend_days := @Integer((temp / 7)) * 2; wkday := @Weekday(DateCreated); adjust := @If(((wkday + @Modulo(temp; 7) - 7) > 0); 2; 0); working_days := temp - (weekend_days + adjust); @If(Currentdate = ""; 0; working_days);

Selected Field Properties


Setting a tab order for a field
Tab order specifies the sequence in which fields become active when a user presses the Tab key. By default, the tab order moves from left to right, top to bottom. You can control the tab order by explicitly assigning a numeric sequence to fields in the Tab order field on the Field Info tab of the Field Properties box.

Chapter 6: Designing Fields 151

Using Native OS Style


If you choose the field property Native OS style for an editable field, such as Text, Authors, Readers, Names, or Number, the field appears on the document as a fixed-size outlined box instead of as blank space marked off by brackets. An editable Date/Time field displays as a graphical date/time control. On the Web, native controls are ignored and fields display in their default format. You can change the width and height of native controls by: Entering a fixed width and height. Choosing Expand width to window. Choosing Dynamic. This option increases the size of the entry box dynamically up to 3 lines. If an entry is longer than 3 lines, scroll bars display automatically.

Automatically refreshing field values


Sometimes users must see the results of all field calculations as they work on a document. To provide continuously updating information, design a form that recalculates fields automatically whenever a field value changes. Be aware this setting slows down a documents display and data-entry time. You can refresh field values in the following ways: Automatically, by setting a form property that refreshes all keyword fields as the user edits a document. Automatically, by setting individual field properties to refresh based on the event you choose. For example, you might set a keyword field to refresh automatically when a keyword changes. Manually, when a user manually refreshes a document. For choice list fields use the field property Refresh field on keyword change for better performance on large documents with many computed fields. This field property refreshes all the fields on a form only after a user selects a value for a specific choice field that has the property enabled. You can also write a LotusScript field event to recalculate the document or update other fields when users move from a specific field.

To refresh field values automatically


1. Open the form. 2. Choose Design - Form Properties. 3. On the Form Info tab select Automatically refresh fields. 4. Save the form.

152 Application Development with Domino Designer

Making a field active by default


The first editable field on a form is the active field by default. You can override this setting and change which field is active when a user creates or edits a document. Changing the default active field helps emphasize an editable field that isnt located at the top of the form, or directs users to a field that is the most frequently edited field on the form or to a required field that you dont want users to miss. This option applies only to editable fields. 1. Create a field, or click an existing field. Then choose Design Field Properties. 2. On the Field Info tab select Give this field initial (default) focus.

Hiding fields
Use hidden fields to perform interim calculations or to store information you do not want users to see. In the Designer templates, hidden fields appear at the bottom of forms, preceded by the heading Hidden fields. Hiding fields is not a security feature. Users can see the value of hidden fields on the Fields tab of the Document Properties box in the Notes client. To keep the data fields safe, encrypt, rather than hide, the fields.

Hiding options
When you hide a field, you are actually hiding the paragraph on the form that contains the field. If there is text, such as a field label or graphics in that paragraph, Designer hides them with the field. You can hide a field and any associated text or graphic all the time or only at certain times. For example, information useful only when users create or edit documents can be hidden during reading, printing, and copying; information that is used for display, such as a computed field that displays the result of an authors choice in an editable choice list field, can be hidden during editing. The following are options for hiding fields: Hide paragraph from Notes 4.6 or later Information is hidden when the application opens on a Notes 4.6 workstation. Hide paragraph from Web Browsers The information is hidden when the application opens on a Web browser.
Chapter 6: Designing Fields 153

If the paragraph is hidden when: Previewed for reading Previewed for editing

Then: The hidden information isnt visible when users read documents in the document preview pane. The hidden information isnt visible when users work on documents in Edit mode in the document preview pane. The hidden information isnt visible when users open documents in Read mode. A field that cant be read cant be printed either. The hidden information isnt visible when users work on documents in Edit mode. The hidden information isnt visible on printed documents. The hidden information isnt visible when information is copied to and pasted from the Clipboard. This setting doesnt affect documents copied at the view level. A formula determines the circumstances in which information is hidden.

Opened for reading

Opened for editing Printed Copied to the clipboard

Hide paragraph if formula is true

To hide a field
If you have computed fields that users dont need to see, or if you create two fields one for display when reading and one for use when editing you can stipulate when to hide the fields. 1. Select the field you want to hide. 2. Choose Design - Field Properties. 3. On the Hide tab: Select Hide paragraph when document is: and click all situations when users dont need to see the field information. or Select Hide paragraph if formula is true and write a formula in the formula window on the Properties box to describe the situations when users dont need to see the fields. For more information on using a formula to hide a paragraph, see the Programming Guide. Choosing Refresh fields when keywords change displays documents faster than the form property Automatically refresh fields. It is useful for showing or hiding parts of the form when you have hide-when formulas that are dependent on values in the field.
154 Application Development with Domino Designer

Examples To make documents more readable, you decide to modify the Marketing Ideas form to show only the model name for the product that the author selects. The Models field is a radio button field that displays these choices for refrigerator models: Econo-Freeze Icebox 2000 InstaFreeze Premium The Chiller You hide the Models field when previewed and opened for reading. You create a computed text field called SelectedModel and locate it under the Models field. SelectedModel uses the value from the Models field. You hide the SelectedModel field when opened for editing. Now when users create a new document, all model names are shown. When users read a document, they see only the model name chosen by the author.

Creating a field in a layout region


If you are designing a field in an application that will be accessed by Notes clients only, placing a field in a layout region allows you to display the field value over text or graphics and limit the number of characters users can enter in a field. In addition, creating certain date/time fields in a layout region automatically displays calendar controls. Creating an editable date/time field in a layout region with Display date selected displays a calendar pop-up that users click on to choose a new date. Creating an editable date/time field in a layout region with Display time selected, displays a time control that let users pick a time by sliding the selection bar to a new time. To make the time control a duration control that lets users pick a range of time, specify that the field can allow multi-values. Then on the Advanced tab, choose Separate values when users enter Blank Line and choose a separator. Layout regions are not supported in Web applications.

Chapter 6: Designing Fields 155

To create a field in a layout region: 1. Open the form. 2. Click the layout region and choose Create - Field. 3. Choose Design - Field Properties and assign a name to the field. 4. Assign any field type except Rich Text and then select Editable or a computed option. 5. Drag the field horizontally or vertically to adjust its width and height. To create a field label: 1. Choose Create - Layout Region - Text. 2. Click the text area, choose Design - Object Properties, and type a field label in the Text box. Click the green check mark. 3. Drag the text area above or to the left of the field and drag it to the size you want. 4. Click the Style tab to change the text style for the label. To resize a field: Placing a field in a layout region allows you to adjust the way field values appear or to limit the number of characters users can enter in a field. To resize a field, drag the borders of the field.

Adding HTML attributes to a field


There are two places to attach HTML to a field. Use the HTML tab on the Field Properties box, or use the HTML attributes field event to attach HTML formatting attributes to editable fields. For example, you can define SIZE and MAXLENGTH for a text field and ROWS and COLS for a rich text field. 1. Click the field you want to format. 2. On the Objects tab of the Info List in the Programmers pane, select the HTML Attributes event for the field. 3. Write the HTML code in quotes in the Script area for example,
"SIZE=40 MAXLENGTH=40"

4. Save the form.

156 Application Development with Domino Designer

Storing HTML in a field


To pass HTML directly to the browser and force Domino to disregard all other fields, add a field named HTML to the form. The field can be computed or editable, but editable is preferable if you want to change the HTML on a per-document basis. Use a text field if the HTML text is less than 15K; otherwise, use a rich text field. Enter the HTML code as the field value in the Script area of the Programmers pane or enter the HTML in the field of the document you create using the form. Using HTML in a field is similar to enabling the form property For Web Access: Treat documents as HTML, but converts only the field value to HTML, so you can keep fields for Notes users on the same form. Web users see the HTML information when they read documents, but they do not see the HTML information when they edit documents. 1. Create a field named HTML. 2. Select Value or Default Value in the Programmers pane object list. 3. (Optional) Write the HTML code in the script area if you want to present the same HTML code for every document created with the form. 4. Save the form. 5. (Optional) Create a document based on the form. In the editable HTML field, write the code you want to display with this document.

Creating fields that inherit values


A field can inherit values from another document in the same database or from another field on the same form. A field that inherits a value from a field on the same form must be a computed field, placed below or to the right of the field it is inheriting from. Use the parent fields name as the value for the field formula. The form itself does not need the Inherit field values property set. To inherit a field value from another form, a Notes client user must have that form selected and a Web user must have the form opened or referenced in the URL command, for example, http://server/db.nsf/InheritanceForm?OpenForm&ParentUNID=6b87e303 374b19148525639a00506656.

Chapter 6: Designing Fields 157

To create a field that inherits values from another document


Create fields that inherit information from another document to save users from unnecessary typing or to keep related documents consistent.Open the form. 1. Choose Design - Form Properties. 2. (Optional) To display the parent document to end users in the preview pane of the Notes client, click the Defaults tab, select On Open: Show context pane and select Parent. 3. Select On Create: Formulas inherit values from selected document. 4. Create the fields that should inherit values. 5. Write a default value or computed field formula for each field that uses the parent document field name as the value. For example, to inherit the FullName field, use FullName as the inheriting fields formula. Example: Inheriting address information In a Customer Contacts application, a Letter form uses inheritance to copy information from a Company Profile document. The Company Profile contains name and address fields and a hidden field called FullName. The Letter form inherits the values of the name and address fields for the address block and uses the FullName field for the salutation. When Notes client users highlight a Company Profile document and choose Create - Letter, the Letter is already filled in with the recipients name, address, and the correct salutation. When Web users open the Company Profile document and click a button to create a Letter document, the Letter is already filled in with the recipients name, address and the correct salutation.

Creating a field that inherits an entire document


You can create a field that inherits the full contents of a document. For instance, a rich-text field in a new response document can automatically inherit the entire contents of its main document. To create a document that inherits the parent document a Notes client user highlights or opens an existing document before creating a new document. The documents do not need a main document/response document relationship. The opened or highlighted document is assumed to be the parent document. The parent document can be inherited in its entirety as rich text, as collapsible rich text, or as a link. Displaying the parent document as collapsible rich-text gives users the opportunity to review the parent document, but doesnt clutter the form. To suppress inheritance a Notes client user can press CTRL while choosing Create.

158 Application Development with Domino Designer

To inherit the parent document a Web browser user must open an existing document before creating the new document. The options Inherit as rich text and Inherit as Collapsible rich text both inherit the topic in its entirety into the new document. Collapsible sections and inheriting as link are not supported on the Web. To enable Web users to create a new document from an open document, you must provide a form action to create a new document. 1. Open the form. 2. Create a rich-text field to store the inherited document. 3. Choose Design - Form Properties. 4. Click the Defaults tab. 5. Select On Create: Inherit entire selected document into rich text field. 6. Enter or Select the name of the rich-text field and select a document display option.

Inheriting information in a response hierarchy


If you have set up a response hierarchy, a response can automatically inherit the subject of the main topic with added text that distinguishes it from the original subject line. For example, if a user creates a main topic with the subject New Product Ideas, then all subsequent responses will have the subject Response to New Product Ideas. Create a field on the main topic form and the response form named Subject. Make the Subject field on the main topic form editable so that the user can enter the subject. Make the Subject field on the response form a computed field which uses the formula:
"Response to " + Subject

For more information on creating a response hierarchy, see Creating a response hierarchy.

Chapter 6: Designing Fields 159

Standard fields used in templates


The following fields are frequently used in the templates that ship with Designer. You may want to follow the same standards in databases you design to maintain consistency and make it easier to share information between forms.
Field name Body ComposedDate From Subject Field purpose Editable rich-text field that stores most of the information in a document. Hidden, computed-when-composed, date/time field that uses the formula @Created. Computed-when-composed, Authors field that uses the formula @UserName. Editable text field that contains a one-line document summary.

Predefined fields with built-in functionality


Designer provides predefined fields that you can use to automatically add functionality that you would otherwise have to program yourself. For example, to design a form with mailing options, you add predefined mail fields such as SendTo and CopyTo to a form. Designer recognizes the fields and provides the interaction with the mail router that routes and delivers the mailed document. If you try to use a reserved name in a way that is different from its intended use or redefine the field, Designer displays an error message.

Reserved fields for mailing documents


Reserved field name MailOptions SaveOptions Sign Encrypt SendTo CopyTo Use Gives users the option of mailing a document Controls whether documents are saved when mailed Signs creators name to prevent tampering Encrypts mail Sends mail to users listed in field Sends copy to users listed in field continued

160 Application Development with Domino Designer

Reserved field name BlindCopyTo DeliveryPriority DeliveryReport ReturnReceipt MailFormat

Use Sends blind copy to users listed in field Delivers mail high, medium, or low priority Returns a report when mail is delivered to recipient Returns a receipt when recipient reads mail Routes mail via cc:Mail

Reserved names for embedded elements


Reserved field name $$ViewBody $$ViewList $$NavigatorBody $GroupScheduleRefreshMode $GroupScheduleShowLegend Use Contains an embedded view Contains an embedded folder pane Contains an embedded navigator Contains a value for refreshing an embedded group scheduling control Valid values for it are 0 and 1. 0 means that the color legend should not display, and 1 means that it should. The default is 1.

Reserved fields for use in billing applications


Reserved field name $ChargeRead $ChargeWrite Use Creates a billing record when a user opens a document that contains this field Creates a billing record when a user creates, copies, edits, or saves a document that contains this field

Reserved fields for general use


Reserved field name Categories $VersionOpt FolderOptions SecretEncryptionKeys Use Categorizes documents Controls version tracking for documents Puts new documents in folders Encrypts documents with secret, rather than public, encryption keys continued

Chapter 6: Designing Fields 161

Reserved field name HTML $$HTMLHead

Use Passes HTML directly to the server Passes HTML information to be hosted within the <HEAD> tag for a document. The passed information might be meta data (using a <META ...> tag) or JavaScript code (using a <SCRIPT ...> tag) or CSS information (using a <STYLE ...> tag). After Web users submit a document, Domino responds with the default confirmation Form processed. To override the default response, add a computed text field to the form, name it $$Return, and use HTML as the computed value to create a customized confirmation.

$$Return

Internal fields on forms


Internal field name $Title Use When a form is stored in a document, the form name is stored in this internal field. To use a different form to display the document, create an agent that deletes this stored form information and designates another form to display the document.

Fields for version tracking


Adding a $VersionOpt field to a form allows users to create new versions of edited documents on a document-by-document basis. To create a computed $VersionOpt field Use a computed text field if you want each document created from a form to have the same version control option. 1. Create a field named $VersionOpt and define it as a computed text field. Computed-for-display and computed-when-composed fields do not work in this situation. 2. Select Value on the Objects tab of the Info List in the Programmers pane.

162 Application Development with Domino Designer

3. In the Script area enter one of the following values:


Value 0 1 2 3 4 5 6 Type of tracking No version tracking New versions become responses if users choose File - Save As New Version when they save a document New versions automatically become responses when saved Prior versions become responses if users choose File - Save As New Version when they save a document Prior versions become responses when saved New versions become siblings if users choose File - Save As New Version when they save a document New versions automatically become siblings when saved

To create a choice list $VersionOpt field Use a choice list field if you want users to be able to choose the method of version control each time they create a document. 1. Create a field named $VersionOpt and define it as an editable dialog list field, in the Field Properties box. Do not select Allow multi-values or Allow values not in the list. 2. On the Control tab select Enter choices (one per line). 3. Enter one or more of the following options: Dont track versions | 0 Create response if File - Save As New Version is used | 1 Create response automatically | 2 Promote to main document if File - Save As New Version is used | 3 Promote to main document automatically | 4 Create additional main document if File - Save As New Version is used | 5 Create additional main document automatically | 6

Chapter 6: Designing Fields 163

Fields that prompt users to select folders


Adding a FolderOptions field to a form lets users select a folder for new documents without having to choose Actions - Move to Folder after saving. You can define the field so that users are prompted to choose a folder or so that a document is automatically saved to the current folder. 1. Create a field named FolderOptions and define it as a computed text field, computed number field, or an editable choice list field. Do not select Allow multi-values or Allow values not in the list. Computed-for-display and computed-when-composed fields do not work in this situation. 2. For a choice list field, on the control tab of the Field Properties box, select Enter choices (one per line) and write each entry, using a keyword and its equivalent synonym for example:
Choose folder from list | 1 Save in current folder | 2

3. For a computed field, select Value from the Objects tab of the Info List in the Programmers pane. For an editable field, select Default value from the Objects tab of the Info List in the Programmers pane. 4. Write a formula in the Script area of the Programmers pane. The FolderOptions field must contain the value or default value 1 or 2. 1 (Prompts user to choose folder) This value prompts the user with the Move to Folder dialog box. Selecting a folder and clicking Add puts the new document in a folder. Selecting Cancel saves the document without putting it in a folder. 2 (Save to current folder) If the user is creating the document from an open folder, this value saves and adds the document to that folder. If the user is not creating the document from a folder, the document is saved but not added to a folder.

164 Application Development with Domino Designer

Chapter 7 Designing Framesets


This chapter introduces frames and framesets.

Overview of framesets
A frameset is a collection of frames and can add structure to your Web site or Notes database. A frame is one section, or pane, of the larger frameset window and is independently scrollable. A frame can contain a form, folder, page, document, view, navigator, or frameset. The frame can also contain a Web page and be associated with a specific URL. Framesets let you create links and relationships between frames. For example, you can leave one page displayed as users scroll or link to other pages or databases.

Designers can set a frameset to launch automatically when a database, form, or page opens.

165

Note Framesets created with Release 5 do not work with previous releases of Notes. A database opened by a previous version of Notes will be launched using restored as last viewed by user.

Creating a frameset
1. Open Designer and choose Create - Design - Frameset. The Create New Frameset dialog box appears.

2. At the Number of frames drop-down box, select two, three, or four frames. You can make adjustments later. 3. Next to Arrangement, click one of the arrangements for the frames. 4. Click OK. The frameset with the chosen layout appears. 5. (Optional) Use the Frame action buttons, the Frame menu options, or keyboard keys to further refine your frameset. You can: Split the selected frame vertically by choosing Split into Columns (SHIFT - INSERT key). Split the selected frame horizontally by choosing Split into Rows (INSERT key). Delete the selected frame by choosing Delete Frame (CTRL - DELETE key). Refresh the content of the selected frame by choosing Refresh Content. Remove the content of the selected frame by choosing Remove Frame Content (DELETE key). Cycle through frames by using the TAB key (SHIFT - TAB cycles backwards).
166 Application Development with Domino Designer

6. Open the Frameset Properties box. At the Basics tab: Name the frameset. Provide an alias for the frameset. An alias is an internal name for the frameset. Use an alias to change or translate the frameset name without causing reference problems. The alias appears with the initial list of framesets in the Work pane. Add a comment. The comment appears with the initial list of framesets in the Work pane. Click Available for public access if you want to have the frameset available for public access. Enter a title for the frameset in the Title field or use a formula to compute the frameset title by clicking Formula Window and entering the formula. The frameset title is the name that appears in the Windows tab when the frameset is launched. 7. Add content to each frame by using the Frame Properties box. 8. To move borders between frames, you can: Drag borders with the mouse. Use the Arrow keys to drag the border in the direction of the arrow and the SHIFT + Arrow keys to drag the border in the opposite direction. 9. To preview the frameset: To preview the frameset on the Web, choose Frame - Preview in Web browser and choose a browser. To look at the HTML source, click Synopsis in the Design pane. In the Design Elements tab of the Design Synopsis dialog box, choose framesets and add each frameset for which you want to view the HTML source. Make sure to check Include JavaScript and HTML in the Contents tab. You can also look at the HTML source by previewing the frameset on the Web and then viewing the source with the chosen Web browser. To preview the frameset in Notes, you can launch the database into the frameset or select the frameset name in the Work pane and click the Preview in Notes icon from the Designer toolbar.

Chapter 7: Designing Framesets 167

Providing content for a frame


When you first create a frameset, the text No content appears in each frame. To provide content for a frame in a frameset, you can do the following: 1. Select a frame in the frameset. 2. Choose Frame - Frame properties. The Frame Properties box appears. 3. At the Basics tab, provide a name for the frame. Make sure that each frame has a unique name. Using the same name for frames in different framesets is not recommended. For example, if you have a frame named Banner in more than one frameset, you may get unexpected results when you set it as a target frame. Note that you should not use HTML predefined target names to name a frame ( _self, _top, _parent, and _blank). 4. At the Type field, choose one of the following ways to provide content for the frame: Link Link requires that you paste in a link that youve already copied to the Clipboard. Click the Paste icon to paste in the link. There are three kinds of links you can paste in from the Clipboard: View, Document, or Anchor. (Database links are not supported in framesets.) See Adding Links for more information on links. Named Element A named element is a design element that you have already created and named. A named element can be a page, form, frameset, view, folder, or navigator. Enter a value (for example, if you already created a page named PAGE1, enter it into the Value field). Alternately, you can click one of the following icons: Formula icon (@) to use a formula that evaluates to a name. Paste icon to paste in a name which you previously copied to the Clipboard. Folder icon to open the Locate Object dialog box and select a design element from a list of elements. If you choose Named Element - View or Folder, an option appears called Simple appearance. If you check this option, the View action bar is hidden when the view or folder is loaded into the frame.

168 Application Development with Domino Designer

If you want a view or folder on the Web, consider first embedding the view or folder on a page or form. If you choose to make the embedded view an embedded view applet, you preserve much of the HTML view functionality and provide features such as resizeable columns, multiple document selection, and scrolling. URL To put a Web page into a frame, choose URL and enter the full URL specification (for example, http://www.lotus.com). You can also paste in a URL or use a formula that evaluates to a URL. You receive an error in the frame if the URL you specify is not accessible. Note that all content rendered in framesets in Designer uses the native Notes Web browser even if your current browser selection is something else. When you click a link in a Web page (in the Notes client or in a Web browser), the link may open within the same Web page or in a new window, depending on the setting for that Web page. 5. (Optional) Enter the target frame for links activated within the current frame.

Specifying a target frame


In addition to adding content to a frame, you can target a specific frame of a frameset so that data opens in the target frame. You specify a target frame in the Frame Properties box or in the Properties boxes of many other elements (such as the properties boxes for pages, forms, outline entries, embedded outlines, group scheduler, and hotspot resources). The target frame set in the property box of the element takes precedence over the target frame set in the Frame Properties box. For example, you create a frameset with three frames: NewPage, Target1, and Target2. You set Target1 as the target frame in the Frame Properties box for NewPage. NewPage also contains a URL link. You set the URL to open in Target2 in the Hotspot Resources Properties box. When a user opens the frameset on the Web or in the Notes client, links in NewPage open in Target1; however, the URL link overrides the target set for NewPage and opens in Target2. If there is no target frame specified in the element, then the target frame set in the Frame Properties box is used. If you specify a target frame that does not exist, the link opens in a new, top-level window. If you do not specify a target frame, the link opens in the frame that contains the link. For more information on specifying a target frame for an individual link or element, see the on-line help for that elements properties box. Note Remember to specify a name (in the Frame Properties box) for any frame that is going to be a target frame.
Chapter 7: Designing Framesets 169

Using the View menu with framesets


When you are designing frames and framesets, the View menu contains the following commands: Refresh all refreshes the content of each frame with changes you have made since opening the frameset. Show Frame Content once you have populated the frames, you can use this menu option to view either the actual content of the frame or a short description of the frame content. For example, instead of an actual Web page appearing in a frame, the frame contains text such as:
Content type: URL Content value: http://www.lotus.com/

Setting the style for frames


You can set properties such as scroll bars, size of frames, and border properties in the Frame Properties box. Note The Web browser you use may not fully support all the properties you can set in the Frame Properties box. To set the style for each frame: 1. Choose Frame - Frame Properties. 2. At the Frame Size tab, you can specify the following properties for each frame: Width and height for the frame You can choose relative, percent, or pixel to specify the frame width and height: Relative sizes the frame relative to the other frames in the frameset. For example, a frame with no frames above or below it is automatically set to relative and is the height of the frameset. Percent sizes the frame as a percentage of the frameset. A frame set to 50 Percent width is half the width of the frameset. Pixel sizes the frame exactly in pixels. Note that if you change the width and height properties for one frame, the width and height of adjacent frames will change; however, the properties of adjacent frames are not automatically adjusted. Adjacent frame properties are adjusted if you drag the borders.

170 Application Development with Domino Designer

Scroll bar properties. Choosing On forces a scroll bar for the frame; choosing Off causes no scroll bar to appear. If you choose Auto, the scroll bar appears if it is needed. The default is Auto. Allow Resizing. If you choose Yes, you allow users in the Notes client or Web browser to change the height and width of frames by dragging their borders. If you choose No, users cannot drag borders to resize the frame. 3. At the Frame Border tab, you can specify the following properties: For Border Style (Applies to this frame): 3-D border allows three-dimensional borders between the current frame and its adjacent frames. Apply to all frames adds three-dimensional borders between all frames in the frameset. For Border Style (Applies to all borders in frameset): Border width (in pixels) The default is 7 pixels. Border color choose a color from the drop-down color chart. Click on the system (monitor) icon at the top of the color chart to get the default color. Click on the wheel icon at the top of the color chart to create a custom color. 4. At the Advanced tab, specify the Frame spacing and margin height and width. Frame spacing. The default is minimal space between frames. You specify spacing between frames in pixels. This property is not supported in the Notes client. Margin height and width. The default is minimal space between the frame border and the frame content. You specify height and width in pixels. This property is not supported in the Notes client.

Launching a database into a frameset


You can have a frameset display automatically when you open a Notes database: 1. Create the frameset you want to display when the database first opens. 2. In the Database Properties box, click the Launch tab. 3. In the On Database Open field, select Open Designated Frameset. 4. In the Name field, select the frameset you want to open. When the database is opened, the specified frameset launches. If a view link, document link, or @command is used to open a database, the frameset may not open.
Chapter 7: Designing Framesets 171

Launching a form or page into a frameset


You can specify that a form (and the documents created with that form) or a page open automatically in a specific frame of a frameset. 1. Open a form (or page). 2. Choose Design - Form properties to open the Form Properties box. 3. Click the Launch tab. 4. In the Frameset field, select the frameset in which you wish to launch documents that are based on this form. 5. In the Frame field, select the frame in which you wish to display documents based on this form. Note that you can select only framesets that are located in the same database as the form on which you are working. Make sure that you have already given the frame a name in the Frame Properties box.

172 Application Development with Domino Designer

Chapter 8 Designing Views


This chapter describes how to design views. Views help users find the documents they want and serve as summaries of the database contents. For information on importing or exporting views, see Appendix B.

Views
A view is a sorted or categorized list of documents. Views are the entry point to the data stored in a database. Every database must have at least one view, although most databases have more than one view. Here are the general steps in planning your view: 1. Before you actually create the view, think about: The type of view you want (shared, private, and so on). Whether the view is a standard view or a calendar view. The categories in the view. Whether you want to create an embedded view on a form, subform, page, or document. Whether the view will be displayed on the Web. If so you may want to consider creating an embedded view on a form, subform, page, or document or consider creating a view applet or an embedded view applet. 2. Create the view by clicking the New View button in Designer. 3. Name the view. 4. Add columns to the view. 5. Set up which documents will display in the view by writing the views document selection formula. 6. Set up what will display in each column by programming the column value. 7. Set up the sorting order for the columns. 8. Set the style for the view, row, and columns. 9. Close and save the view.
173

In addition to creating views, you can create folders. Folders are containers used to store related documents or groupings of documents. Folders have the same design elements as views and are designed in much the same way as views. You embed a folder pane in the same way you embed a view.

Standard views
A standard outline view is a table of contents for a database and is the most common type of view. It organizes documents by rows and columns. Each column displays a type of information about the document, such as author or date of creation. Each row displays selected pieces of information from one document. One column in the view is usually the organizing element for example, a column entitled Date might organize the documents in chronological order. In a discussion database, you might use a column entitled Topic to display the contents of the Subject field for each document in the view. In a tracking database, it might be the customer or product name. Here is the same view from a review database as shown through Netscape Navigator and through Notes.

174 Application Development with Domino Designer

Standard views, whether in Notes or on the Web, contain the default settings in the View Properties box. For example, the checkboxes in the For Web Access section of the Advanced tab of the View Properties box are not checked. If you want to create a view for the Web, consider creating a view applet or embedded view applet. To open a document in a standard view, Notes users double-click a row; Web users click a document link in one of the columns. A standard view on the Web maintains the column and row format of standard Notes views (unless you use HTML formatting to customize a view), except that on the Web, a navigation bar on the top or bottom of the screen contains buttons that users click to expand, collapse, and scroll the view. On the Web, each time you open, scroll, expand, or collapse a view, Domino converts the view to an HTML page. Each snapshot of the view is a newly generated HTML page. The concept of a selected document in a view in Notes does not apply to a view on the Web. To prevent line wrap on the Web, specify 1 in the Lines per heading setting in the View Properties box. Domino converts this setting to a NOWRAP HTML attribute. Specifying a number greater than 1 causes lines to wrap on the Web. The same guidelines are true for the Lines per row setting.

Chapter 8: Designing Views 175

Calendar views
A calendar view groups documents by date. In fact, the first column of a calendar view must evaluate to a date and time. Such views are useful for organizing schedules, meetings, and appointments.

When you create a calendar view, users have access to the following features: Choices for viewing entries in a Two-Day, Week, Two-Week, Month, or Year format. Point-and-click navigation among days, months, and years. The ability to create new calendar entries and edit existing entries. Integrated Task, Event, and Anniversary display. The ability to print calendar entries for a selected range of days. Web users can see all calendar entries. Domino converts calendar views to HTML tables. Therefore, Domino restrictions for tables also apply to calendar views. You cannot create new appointments or scroll through entries within a single day on the Web.

176 Application Development with Domino Designer

Converting a view to a calendar view


You may have an existing view which you want to convert to a calendar view. A calendar view is similar to the standard outline view except that the calendar view is limited to sorting only on a Time/Date field, which must be the first column in the view. The Mail template contains an example of a calendar view. 1. Create the first column based on a field with a value of both date and time. (for example, creation date and time) and choose a Sort option (for example, ascending or descending) in the Column Properties box. Make sure you specify both a date and a time, even if the time is 00:00. 2. Create the second column based on a field with a number value that specifies the duration, in minutes, of a calendar entry. 3. Create a document selection formula for the view. The formula should select all documents containing the Time/Date field. 4. Choose Design - View Properties and select Calendar as the style. If you select the column sorting option Show multiple values as separate entries for the first column, documents display under different dates. Otherwise, they display only under the first matching date. The Mail template uses this technique for displaying repeating events. Troubleshooting a calendar view If the calendar view does not display as you expect, there may be a problem with the selection formula or with the definition of the first column. Check the selection formula for the view. Make sure the documents you want to display in the view match the selection formula. To test the selection formula, change the view to a standard view or refresh the view while in Designer. If the documents display, the selection formula is valid. Make sure the first column of the view is based on a Date/Time field and is sorted in ascending order. Display the column in Designer. Both the date and time should display. The date determines where the document displays in the view, and the time sorts entries in the correct order, so that a 9:00 AM appointment displays before a 3:00 PM appointment. The first two columns of a calendar view define the Date/Time and the duration of an appointment. Make these hidden columns. To display the time, create a separate time column.

Chapter 8: Designing Views 177

Shared and private views


There are two main types of views: shared (available to many users) and private (available to one person). In addition, you can create a view that changes from shared to private on first use. You designate the view type when you create the view and cannot change it later.

Shared views
Shared views are available to any user with at least Reader access to the database. Most views that you design for databases are shared views. Users with Designer or Manager access can create shared views, as can Editors for whom the manager has selected Create personal folders/views in the access control list. You can create the following specific types of shared views: Shared, contains documents not in folders Shared, contains deleted documents (used in conjunction with Allow soft deletions in the Advanced tab of the Database Properties box) Shared, private on first use Shared, desktop private on first use (saves private views in users desktop.dsk files rather than in the database) Shared, contains deleted documents A Shared, contains deleted documents view allows you to view a list of documents in the database which have been deleted. You can recover deleted documents by dragging them out of the trash to the folder where you want them. This view assumes that the database manager has already selected Allow soft deletions at the Advanced tab of the Database Properties box. The Allow soft deletions property lets deleted documents remain in the database and not be permanently removed for a set number of hours. The hours are set by the database manager in the Advanced tab of the Database Properties box. After that time, the document is permanently deleted from the database. Shared, private-on-first-use views A Shared, private-on-first-use view begins as a shared view and becomes a private view as soon as a user accesses and saves the view. These views are a convenient way to distribute customized personal views to multiple users. You usually create this type of view by using @UserName to customize the display for each user.

178 Application Development with Domino Designer

After a user saves a shared-to-private view, the users copy of the view no longer inherits design changes. For example, if you add a column to the view, anyone using a private version of the view wont see the new column. To obtain design changes, users must delete their private versions of the view and open the shared-to-private view again. Shared-to-private views are not a security measure, as they do not protect data. If you create a shared-to-private view that omits certain documents, a user can still create a private view that includes them. Shared-to-private views are stored in the database as long as they are shared. After the first use, Domino uses the Create personal folders/ views option to determine where to store the view. Shared, desktop private-on-first-use views If you want the shared-to-private view to be stored in a users desktop.dsk files rather than in the database, choose Shared, desktop private on first use as the View Type when you create the view.

Private views
Users can create private views to organize documents in personalized ways by choosing Create - View. If a user has rights to create private folders/views in the access control list, private views are stored in the Notes database. If the user does not have the access control list right to create private folders/views, personal views are stored in the users personal workspace file (desktop.dsk). Private views are not supported on the Web.

Creating a view
To design a view, you must have Designer access in the access control list of the database. For information on database access, see Managing Domino Databases. 1. Select or open a database in Designer. 2. Click Views in the Design pane. 3. Click the New View button above the Work pane. The Create View dialog box appears. 4. Enter a name for the view in the View name field. 5. Choose a View type in the View type field.

Chapter 8: Designing Views 179

6. Select a location in the Select a location for the new view field. If you want the view to appear at the top level, do not select anything in this field. Otherwise, click the name of the view under which you want the new view to appear. 7. Click the Copy style from button. Click Blank if you do not want to copy another views style. Otherwise, click the view whose style you want to copy. If the style uses selection by formula, the views selection criteria appears in the Selection criteria field. 8. (Optional) You can use the Fields and Functions button and Formula window button to further refine the new views selection criteria. 9. Click OK to create the new view. 10. Double-click the new view in the Views list to open it. 11. Click the column labeled #, choose Edit - Clear, and Yes to confirm. 12. Choose Create - Insert New Column to create the first column. 13. Add other columns by choosing either: Create - Insert New Column to create a column to the left of the highlighted column. Create - Append New Column to add the column after all existing columns. 14. To give each column a title, choose Design - Column Properties and click the Column Info tab. Enter a name in the Title field. 15. Click each column in the Work pane. In the Programmers pane, add programming to determine the column value. For example, a column can list the creation date or the size of each document. 16. Click the current view in the Objects list and expand it. Select View Selection and add programming for the views document selection. 17. Choose Design - View Properties and click the Style tab to style the view. 18. Click each column and choose Design - Column Properties. Click the Title tab to determine the font, size, color, and alignment of the column title. Click the Font tab to do the same for values that display in the column. 19. Close and save the view.

180 Application Development with Domino Designer

Default design for new views To save design time, designate a view as the standard for newly created views or folders in the database. To use a view as the design standard, open the view in Designer and select Default design for new folders and views on the Options tab of the View Properties box. Copying and deleting views and columns To copy a view, click Views in the Design pane, in the Work pane click the view you want to copy, choose Edit - Copy, and then Edit - Paste. A copy of the selected view appears in the list of views. Until you rename it, the copied view is named Copy of <selected view name>. To delete a view, click Views in the Design pane, in the Work pane click the view you want to delete, click the view name, and choose Edit - Clear. To copy a column, open the view in Designer, click the column, copy it to the clipboard, select the column to the right of where you want the column to appear, and choose Edit - Paste. To delete a column, open the view in Designer, click the column, and choose Edit - Clear. Limits for views A view can display no more than 32 levels of responses and/or subcategories. For example, if you have 6 levels of subcategories, you can display 25 levels of responses to a main document. If there are more levels of responses than can be displayed, convert your view to a non-hierarchical, flat view, which displays all documents on a single level (by deselecting Show response documents in a hierarchy in the View Properties box). The combined number of sub-level forms, views, and agents that cascade from the top level cannot exceed 200; otherwise, the top-level menus do not display properly. This limit does not apply to the number of forms, views, and macros stored at the top level of each menu. Domino allows up to 200 cascading view and folder names to be displayed on the View menu.

Naming a view
The name you choose for a view is visible to Notes users in the View menu and in the folders pane (unless the view is hidden). The view name is visible to Web users in the Views list. The name is case-sensitive and can be any combination of characters, including letters, numbers, spaces, and punctuation. The full name, including all aliases, can have up to 64 characters.
Chapter 8: Designing Views 181

Naming tips
Views appear in alphabetical order in the View menu in Notes and in the View lists on the Web. To force names to appear in a different order, number or letter them. For example: 1. Zebra 2. Antelope If you start a name with a hyphen (-), the name appears before both numbers and letters. When possible, assign a name that indicates how the view sorts documents for example, By Company Name or All by Category or specifies which documents it includes, for example, New Customers. Use consistent names across databases to make it easier for users to recognize views.

Aliases
An alias is another name, or synonym, for a particular view. Use an alias to change or translate the view name without causing lookup formulas that reference the view to stop working. Aliases follow the same naming rules as view names. Enter an alias in the Alias field of the View Info tab of the View Properties box. You can append more than one alias by entering the | (vertical bar) symbol followed by the alias. Make sure you keep the original alias as the rightmost name.
Main View | Top View | View1

Changing a view name


You can edit the view name or alias in the View Properties box when the view is open in the Designer. If you change the name of the view, copy and paste the previous name into the Alias box to the left of any other aliases, using | as the separator. For example, your movie database is going to be converted to German. The translators change the name By Premiere Date to display the view name in German on the View menu. They enter the new name in the Name field of the View properties box:
Nach Premierendatum

To keep both By Premiere Date and DateView as aliases, they enter the following in the Alias field of the View properties box:
Nach Premierendatum | By Premiere Date | DateView

182 Application Development with Domino Designer

Naming guidelines
Hidden views When you surround a name with parentheses for example, (All) the view does not appear to Notes users in the Notes View menu or to Web users or Notes users in the list of folders and views. For other ways to hide views, see Hiding a view later in this chapter. Shortcut keys Windows, OS/2, and UNIX users can type shortcut letters to select a view. The default shortcut, an underlined letter in a view name, is the first letter in the name that has not already been used by a preceding name on the menu. But if views or folders begin with the same letter, the default shortcut is the first letter that has not already been used by a preceding name. If views or folders begin with the same letter, the shortcut letters may be difficult to see and remember. For example, the shortcut letters (underlined) for these views are
By Author By Date

You can rename the views and omit the repeated word, but in some cases the word is needed to make the names understandable.
Authors Dates

If you cant change the names, you can specify a more meaningful shortcut by typing an underscore before the letter D to assign it as the shortcut for the By Date view, entering the name as
By _Date

Cascading views Creating cascading views lets you arrange lists of views in a hierarchy; that way, a group of related menu items are organized under one item. A user clicks on the higher-level name to display the cascaded list. You probably want to cascade views when you have long lists of views or when you have related views that should be grouped together. To create a cascading view, enter the name you want to appear on the Create menu followed by a \ (backslash), followed by the view name. For example, the Personal Address Book template has two views related to servers:
Server\Certificates Server\Connections Chapter 8: Designing Views 183

Columns
Columns display one type of information about the documents listed such as the document subject, author, or creation date. One column in a view is usually the organizing element for example, in a chronological view, the organizing column displays document creation dates. To add a column to a view in Designer, choose Create - Insert New Column or Create - Append New Column. A view can have a single column or as many columns as you can fit in 22.75 inches (the allotted width of a view).

Adding titles to columns


A title is optional text at the top of a column that helps users identify the type of information in the column. Assign a title using the Column Properties box. The title can be a static text label, such as Subject or Date, or a message such as Open a document below to see or change the schedule. To avoid cluttering the view, dont include titles for every column.

Omitting a title
If you leave the title blank, the column doesnt have any identifying text. Omit a title if the column is: A responses-only column that indents response documents A categorizing column Hidden (and designers dont need any identifying text when the view is Designer) Not relevant to users

Guidelines
Column titles can contain up to 80 characters in any combination of letters, numbers, and punctuation. To change the font, size, or color of a column title, choose styles from the Title tab of the Column properties box. To allow long titles to wrap to several lines in Notes, set the Lines per heading in the Style tab of the View Properties box to a number greater than 1.

184 Application Development with Domino Designer

Note that long titles do not wrap on the Web. To prevent line wrap on the Web, specify 1 in the Lines per heading setting in the View Properties box. Domino converts this setting to a NOWRAP HTML attribute. Specifying a number greater than 1 causes lines to wrap on the Web. The same guidelines are true for the Lines per row setting. The number of characters that fit on one line depends on the font and size you select, as well as the width of the column. If a title is not set up to wrap to more than one line and the text is too long for the width of the column, the text is truncated.

Adding categories to views


A category is a grouping of related documents. A view that displays categories enables users to find those related documents. For example, in an employee view, you can create a category called Ohio and include in that category documents created by only those employees who work in Ohio. A categorized view is neat and easy to scan. Users can collapse the categories to display only the category names, and then expand categories individually, or expand the whole view.

To categorize a view, create a column to display categories and then select the option Type: Categorized on the Sorting tab of the Column Properties box. The resulting column, called a categorized column, groups documents with matching values and converts the common value to a category name. The column is usually one that appears on the left side of the view. This column must always appear to the left of any sorted columns.

Chapter 8: Designing Views 185

Other options include: (Recommended) At the Text Properties tab of the Column Properties box, choose a different color for column text and use bold face to make categories stand out. (Recommended) At the Sorting tab of the Column Properties box, select the column style: Sort: Ascending or Sort: Descending to organize the category names. (Sort: Ascending organizes the categories in alphabetical order and descending in reverse alphabetical order.) (Recommended) At the Column Info tab of the Column Properties box, select Show twistie when row is expandable to display a triangle that users click to see categorized documents. (Optional) At the Options tab of the View Properties box, select Collapse all when database is first opened to show only the category names when users open the view. (Optional) At the Advanced tab of View Properties box, select Dont show categories having zero documents so that categories with no documents associated with them are not listed.

Categorizing in the All by Category view


To let users categorize documents with Actions - Categorize, a database must have these components: A form with a Categories field Field name: Categories Data type: Editable text or choice list field Select Allow multi-values Format: If you selected a choice list field, leave the choice list blank and select Allow values not in list A view named All by Category In the All by Category view, a Categories column placed as the leftmost column. Width: 1 character Column title: Leave the column title blank Formula: Categories; Sort the column by selecting Sort: Ascending and Type: Categorized

186 Application Development with Domino Designer

Generating category names


A categorized column derives its values from the programming attached to the column. For example, to use creation dates or author names as categories, choose @Created or @Author when you program the column. A categorized column can also be set up so that the column gets its values from a Categories field on a form.

Setting up a Categories field


You can produce a categorized column based on a Categories field. To set up a categorized field, add a text or choice list field to the form and name it Categories. A predefined list, user input, or lookup formula can populate the field with values. To categorize documents created with the form, choose Actions Categorize.

Setting up categories in advance


To set up a predefined list of categories, create a computed choice list field and enter the category names as its values. Converting choice list field aliases to full category names If you base a categorized column on a choice list field that contains aliases for the fields, those aliases are used as the category names. For example, a RequestType field that contains the following choice list fields displays the category names as HW, SW, and SVC: Hardware Request | HW Software Request | SW Service Request | SVC To display the full names of a choice list field that uses aliases, use a hidden field or column formula that converts the aliases back to their full names:
@If(RequestType="HW";"Hardware Request";RequestType="SW"; "Software Request";"Service Request");

Chapter 8: Designing Views 187

Letting users create categories in the Categorize dialog box


To let users enter their own categories in the Actions - Categorize dialog box, include an editable, multi-value, choice list field called Categories on the form and select the field option Allow values not in list. Generating dynamic lists of categories To generate dynamic lists of categories, create a choice list field named Categories. Then, use the @DbColumn formula to calculate values for the field. Examples: Generating category names Displaying the names of months This formula is useful for a categorizing column that displays the name of each month as a category name. Dates need to be converted to a text value to be displayed in a view.
m :=@Month(@Created); @If(m = 1; "January"; m = 2; "February"; m = 3; "March";m = 4; "April";m = 5; "May"; m = 6; "June";m = 7; "July";m = 8; "August";m = 9; "September"; m = 10; "October"; m = 11; "November"; m = 12; "December"; "")

To sort these in proper order, add a hidden column to the left of this column that sorts documents in ascending order with the formula
d :=@Month(@Date); @If(d = 1; "A"; d = 2; "B"; d = 3; "C"; d = 4; "D"; d = 5; "E"; d = 6; "F"; d = 7; "G"; d = 8; "H"; d = 9; "I"; d = 10; "J"; d = 11; "K"; d = 12; "L"; "")

Adding subcategories to an All by Category view In your Furniture Catalog database, you want to add subcategories, indented under the main categories, to make documents easier to find in the All by Category view. Subcategories are indented under main categories automatically in a categorized column. You can have 32 levels of subcategories. The Categories field of the Furniture Description form is an editable choice list field with the following entries:
Bedroom Kitchen Living Room

188 Application Development with Domino Designer

To add subcategories, rewrite the choice list choices as follows, update existing documents, and refresh the view. A backslash (\) after a main entry denotes the subcategory name.
Bedroom\Beds Bedroom\Dressers Kitchen\Tables Kitchen\Chairs Living Room\Sofas Living Room\Tables

Recategorize the documents that already exist to assign them to one of the subcategories. You can do this manually with Actions - Categorize by typing the full subcategory specification (Bedroom\Beds) into the Categories dialog box. If there are many documents, create agents that set the new values for the Categories field of each document. Press SHIFT+F9 to rebuild the view index so documents display with their new subcategory names.

Programming which documents display in a view


When you design a view, you can program it to show all documents or only certain documents in the database. Most databases have one view that shows all documents and other views that show a subset of documents. The default selection for new views is the combination of the SELECT statement and the @All formula: SELECT @All, which means include all database documents in this view. To narrow down the kinds of documents the view displays, add a program that displays only particular documents. For example, in a task-tracking database, the Work in Progress view could display only those documents whose Status field does not contain Complete. In a brainstorming database, the Design Ideas view could display all documents categorized as Design Suggestion. Here is a program that displays only documents containing new features and displays them in a Whats New view: SELECT @IsMember(01 Whats new? ; View)

Chapter 8: Designing Views 189

Choosing the type of program


With a view you program the document selection in the Programmers pane. Choose View Selection in the Objects box, select the type of programming you want to add, and build the program in the window below.

Easy Easy allows you to create a conditional document selection without knowing a programming language. In the Info List of the Programmers pane, click the Run drop-down box and select Easy. Then click Add Condition for each selection you want to include. To delete a condition, click it and choose Edit - Clear. Formula Formula allows you to create a program for selecting documents. The program uses the @function formula language. In the Programmers pane, click Formula and write the formula in the Script area. Examples: Programming documents to display in a view Selecting documents by form name and field value If a database contains an Action Item form that contains a Status field, a view in the database can select all documents that were created with the Action Item form whose Status field contains the value Open. The document selection formula is:
SELECT Form ="Action Item" & Status="Open"

190 Application Development with Domino Designer

Selecting only non-response documents To select only documents that were created with main document forms and exclude documents created with response or response-to-response forms, use this formula:
SELECT !@IsResponseDoc

Selecting main and response documents If a database contains a form called Action Item, you can select all documents that were created with the Action Item form, as well as responses to these documents, using the formula:
SELECT Form = "Action Item" | @IsResponseDoc

Selecting documents not created with a specified form The Databases by Title view in the Database Library template selects all documents that were not created with the Librarian form using this formula:
SELECT Form != "Librarian"

Table of document selection conditions for views


When you click Easy as the Run: View Selection formula, you have these selection options. You can combine multiple conditions to narrow down the selection. Click Add Condition to see the full list.
Condition By Author By Date Selection 1 contains does not contain date created date modified Selection 2 <author name> or choose from Address Book is on is after is before is not on is in the last <n> days is in the next <n> days is older than <n> days is after the next <n> days is between is not between contains does not contain continued

By Field

<field name>

Chapter 8: Designing Views 191

Condition

Selection 1 <date field name>

Selection 2 is on is after is before is not on is in the last <n> days is in the next <n> days is older than <n> days is after the next <n> days is between is not between is equal to is greater than is less than is not equal to is between is not between <field values> for multiple fields

<number field name>

By Form By Form Used

<form name> <form name>

Table of document selection conditions Easy conditions The Easy condition determines whether a field contains one value. Because the Easy condition reads any separators you enter as text, it cant look for all the values in a multi-value field. The Easy condition also cant determine whether a particular field is present in a document. You must click Formula and write a formula to do that. Selecting documents by author Documents must have an Authors field for this selection method to work. When selecting By Authors, enter a name or names, separated by commas. If you know a users hierarchical name (such as Mary Sen/Development/ Acme), enter it. If you are not sure of how a name is spelled, use the Public Address Book to browse for person names, but do not select any group names. For more information, see Addressing a message by choosing names from an Address Book in Notes Client Help.

192 Application Development with Domino Designer

Selecting documents by date The Date created condition selects documents based on the Created date in the Document Properties box. The Date modified condition selects documents based on the Modified date in the Document Properties box. Selecting documents by field value If the field is of type Text, Designer looks for the exact text string you enter. You cant enter (empty quotes) to select documents in which the field is empty. You must click Formula and write a formula to do that. For example, to select documents where the Research field isnt empty, use this formula:
SELECT Research != ""

For example, to select documents that have the field Research, use the formula:
SELECT @IsAvailable(Research)

By form name When selecting By Form as a condition for a selection formula, the condition works only with forms that are part of the database design, not with forms stored in documents. Selecting main and response documents with a formula By default, selection formulas include only documents of the type Main Topic. You can include response documents in a selection formula created with one of the simple functions above by editing the formula Notes creates and appending
| @IsResponseDoc

Chapter 8: Designing Views 193

Adding programming to columns


The values each column shows are determined by a program attached to the column. The Programmers pane helps you add programming to a column. Click the column you want to program, click the Simple Function, Field, or Formula button in the Programmers pane, then build the program in the Info List. Column formulas can consist of a combination of @functions, @commands, field values, and text enclosed in quotation marks.

Simple functions
Simple functions let you add programming without knowing a programming language. The default selection for a new column is # in View, which numbers documents according to their internal sequence (for example, 3.1.2).

Field
Field lets you populate the column with field values without writing a program. This technique works only with text fields because columns need a conversion formula to interpret other types of data that is, dates, rich text, or numbers, or encrypted text.

194 Application Development with Domino Designer

Formula
Formula lets you create a program for a column using the @function formula language. This is useful when you must process values in a document (such as changing field values to a text value) or calculate a value. Typical uses for formulas include converting field data to a text value (because only text values display in columns), writing a formula that displays an icon instead of a value, and adding text to field values. Click the Field button or the Simple Function button to paste fields, @functions, or @commands into the formula. Always convert information to the data type that your formula expects. For example, to append a numeric value to a text value in a column, use a formula like:
Product + ": " + @Text(Quantity)

Examples: Adding programming to columns Determining text, based on a field value In a column, you can show custom text based on a condition or on a number of conditions. For example, you can create a formula that displays custom text if sales exceed a certain amount. This formula tests the value in the Sales_February field (a number field) and displays text based on that value:
@If(Sales_February>60000;"Great month!";"")

Determining text, based on the form name The Subject column in the All Documents view of the Mail template uses the following formula. It displays a subject line based on the form the document was created with.
@If(Form = "NonDelivery Report"; "DELIVERY FAILURE: " + FailureReason; Form = "Delivery Report"; "DELIVERED: " + Subject; Form = "Return Receipt"; "RECEIVED: " + Subject; Form = "ReturnNonReceipt"; "NOT RECEIVED: " + Subject; Subject)

Combining text and dates You can combine text and field values in a column in a scheduling database to add an explanation about the documents. The formula below displays a text message and a date, with two variations that depend on the value in the Sched field. The D1S0 part of the @Text formula is a formatting option that removes clutter from the view by showing the month and day portion of the date field only and omitting the exact time.
@If(Sched = "Special schedule"; "Special schedule for the week of: " + @Text(Date; "D1S0"); "My regular schedule, as of " + @Text(@Modified; "D1S0"))

Chapter 8: Designing Views 195

Combining text and names The following formula results in three possible results, based on the status of a request: @If(Status=Rejected ;Rejected by + LastApproveName; SignatureCount=0; Original Request ;Approved by + LastApproveName) If the request has been rejected, the column displays Rejected by and the name of the person who last signed the form. If the request has no signatures (meaning that no approver has acted on the request), the column displays Original Request. If the request has been approved, the column displays Approved by and the name of the person who last signed the form. Showing when a document was created The Created column in the By Author view of the Document Library template uses the following formula to display the date on which the document was created:
@Created

Expandable levels (variation on the simple function) The simple function Collapse/Expand (+/-) uses @IsExpandable without any arguments. If you want to display a + (plus symbol) when a document has responses, but suppress a - (minus symbol) when responses are expanded, use the formula:
@IsExpandable("+";"")

Displaying two field values in one column To show peoples names and phone numbers together in one column, create a column that is sorted in ascending order (the recommended order for alphabetical listings). The following formula separates the two field values with a blank space:
Name + " " + Phone

Creating fake indenting When Notes indents response documents, the indentation is always the same. If you want to make a document in a flat view appear indented without using response documents, or display document titles in the same column at different indentations, you can use a field on the form to determine how much each document indents and use a column formula that appends space characters to the document titles in the view. The following formula indents documents in three different ways depending on the value in the Indent field. For example, if the value of the Indent field is 3, Notes prepends 18 space characters to the Subject of the document in the column.
196 Application Development with Domino Designer

@If(Indent = 1; @Repeat(" "; 12) + Subject; Indent = 2; @Repeat(" "; 18) + Subject; @Repeat(" "; 6) + Subject)

Numbering documents In a By Author view, the following formula numbers (as in 1., 2., 3.) each of the documents within each authors category:
@IsCategory("";@DocNumber("") + ". ")

If the row is a category (the authors name), @IsCategory returns a null string (). If the row isnt a category, then the row represents a document, and @DocNumber returns a string that represents the entry number of the document. The documents full entry number is something like 1.1, 1.2, 1.3, and so on, but when used with the null string ( ), @DocNumber returns the rightmost component of the entry number. The formula then adds a period and a space . after the number.

Table of simple functions for columns


The following simple functions (that is, functions that let you add programming without knowing a programming language) can be used with columns.
Function name Attachment Lengths Description Displays the file size of document attachments. The data type is a number list. Example

Attachment Names Displays the file name of document attachments. The data type is a text list.

Attachments

Displays the number of files attached to each document. The data type is a number.

continued

Chapter 8: Designing Views 197

Function name Author(s) (Distinguished Name)

Description Displays document author name in hierarchical format, as in Denise Lee/Research/Acme.

Example

Author(s) (Simple Name)

Displays the document author name without its fully distinguished format, as in Denise Lee.

Collapse/ Expand (+/-)

Use in a column styled as a Sorted/Categorized column. Returns a + (plus symbol) if the view entry has descendants that are not visible because the main document is collapsed. Returns a (minus symbol) if there are no subordinate documents or if subordinate documents are currently visible. Useful when a view contains a large number of response documents. Displays the time and date a document was created.

Creation Date

Last Modified

Displays the date when a document was last saved.

Last Read or Edited

Displays the last time and date a document was read or edited.

continued

198 Application Development with Domino Designer

Function name Size (bytes)

Description Displays the file size of documents.

Example

# in View

Displays a number for each document indicating its order in the view. Responses are numbered in outline style under Main documents for example, the first response to the first main is 1.1. Displays the number of direct descendant (response) documents for a document or next-level subcategories for a category.

# of Responses (1 Level)

# of Responses (All Displays the total number of Levels) descendant (response and response-to-response) documents for a document or subcategories for a category.

Chapter 8: Designing Views 199

Displaying an icon in a column


To make certain types of documents stand out in the view, display icons instead of text in a column. The Combined Mail template uses icon columns in the All Documents view to flag different types of documents:

An icon column has two requirements: The column property Display values as icons is selected. The column uses a formula that results in a number that corresponds to the icon you want to display. The graphics used in column icons cant be customized, but you can choose from more than a hundred predefined column icons.

Programming columns to display icons


The following formula determines whether a document has an attachment and, if so, displays the attachment icon (number 5):
@If(@Attachments;5;0)

Use 0 as the false case when you want to leave the column blank. The formula above returns 0 when the document has no attachments, so nothing is displayed. A column that displays icons cant display anything else, such as a plus (+) sign for an expandable categories column.

Table of column icons


The figure below shows the available column icons and their values. The values for the icons in the first column are numbers from 1 to 20. The value for any icon in the rest of the columns starts with the number shown in the column heading, for example 41, and increments by 1 for each row in that

200 Application Development with Domino Designer

column. You cant add your own icons; you must choose from the icons shown below.

Sorting documents in views


Every view needs a sorting method that organizes documents in a way that makes sense to users. For example, a By Date view sorts documents by their creation dates, and a By Author view sorts documents by author names. To achieve this effect, designate at least one column as a sorting column. Then define it as a user-sorted column, an auto-sorted column, or both. Views that display categories often use sorting methods to alphabetize the category names. If the sort column displays values from a multiple-value list, select Show multiple values as separate entries to show each value as a separate row. If you dont set this option, multiple values display as one entry and sort by the first value. Note that sorting columns is not supported on the Web.
Chapter 8: Designing Views 201

User-sorted columns
Users see a triangle next to a column title whose values can be resorted. Users click the column and choose a sorting method to see the documents in the order they choose.

To set up a user-sorted column, select the option Click on column header to sort on the Sorting tab of the Column Properties box. Then select Ascending or Descending order, or select Both to allow users to cycle among ascending sort order, descending sort order, and no sort order for the column.

Auto-sorted columns
To set up a sorting style in advance, select the option Sort: Ascending or Sort: Descending on the Sorting tab of the Column Properties box. The sorting column is usually one that appears on the left side of the view.

Multiple sorting columns


To create multiple levels of sorting, designate more than one column as a sorting column. For example, if a primary sorting column sorts entries by date, a secondary sorting column might sort entries by author. Then all documents created by one person on a particular date are grouped together.

202 Application Development with Domino Designer

Using an auto-sorted column as the secondary sorting column To add a secondary sorting column, add a column to the right of the first sorting column and then choose Sort: Ascending or Sort: Descending on the Sorting tab of the Column Properties box. Documents and responses are sorted, then sub-sorted, in column order from left to right. Designating a secondary sorting column for a user-sorted column User-sorted columns override the sorting built in to auto-sorted primary and secondary columns. If the view has a user-sorted column and you want to include secondary sorting, you can associate it with a secondary sorting column. On the Sorting tab of the Column Properties box for a user-sorted column, click Secondary sort column and choose the secondary sort column and its sorting order.

Ascending and descending order


Columns sort documents in ascending or descending order: Ascending order sorts in increasing order (1 precedes 2, A precedes B, earlier dates precede later dates). For example, to display documents from oldest to newest, create a Date column that uses the Creation Date as its value and sorts documents in Ascending order. Descending order sorts in decreasing order (2 precedes 1, B precedes A, later dates precede earlier dates). For example, to display documents from newest to oldest, create a Date column that uses Creation Date as its value and sorts documents in Descending order.

Character sorting rules


After the ascending or descending order is set, characters are sorted in this order: numbers letters accented letters punctuation/special characters

Chapter 8: Designing Views 203

Case-sensitive and accent-sensitive sorting rules for Release 5 differ from sorting rules in previous releases in the following ways: Both case-sensitive sorting and accent-sensitive sorting are turned off by default (in previous releases, they were on by default). Case-sensitive sorting sorts lowercase letters before uppercase letters for example, ab sorts before Aa. Accent-sensitive sorting sorts accented characters after non-accented characters. For example, ab sorts before a.

Overriding alphabetical sorting with a hidden column


The sorting column does not need to be visible. Sometimes you may want to use a hidden column as your sorting column. For example, a Service Request form contains a Priority field, which uses the following choice list:
Urgent High Medium Low

You want the By Priority view to sort documents by the value in the Priority field, but you dont want them to appear in ordinary alphabetical order (High, Low, Medium, Urgent). You want users to see Urgent-priority documents at the top of the view, High-priority documents next, and so on. You create a column that: Is hidden Has no title Is one character wide Uses this formula to determine the order of each priority:
@If(Priority="Urgent";"1";Priority="High";"2"; Priority="Medium";"3";"4")

Is sorted in ascending order You add a column to the right of the hidden column that: Is not hidden Has the title Priority Is 10 characters wide

204 Application Development with Domino Designer

Displays the value of the Priority field Is not sorted

Customizing which column links to Web documents


To open a document from a view, Web users click a column that links to the document. By default, Domino uses the leftmost column in a view as the linking column, but you can change this default by designing another linking column. After you set up customized linking, you cannot revert to Dominos default behavior you must continue to designate at least one linking column in that view. 1. Click the column(s) you want to display as linking columns. 2. Open the Column Properties box and click the Advanced tab. 3. Select For Web Access: Show values in this column as links.

Adding pass-thru HTML to a column


To insert HTML in a column, click Formula in the Programmers pane, select Column value in the Object list, and add HTML as the column value in the script area. Notes users may see the HTML if it is used in a view they can see. The following formula inserts the graphic new.gif if the document was created within the last five days; otherwise, no graphic is displayed.
@IF (@NOW > @ADJUST(@CREATED; 0; 0; 5; 0; 0; 0); "";" [<img src=/gifs/new.gif border=0>]")

Using a column to switch to another view


To give users an easy way to see additional, related information that doesnt fit in the initial view, use a column as an entry point to another view. Users click such a column to open another view. To set this option, choose Click on column header to sort on the Sorting tab of the Column Properties box. Use the column title to alert users to this special kind of column. For example, you can title the column Click here to switch to the By Author view.

Chapter 8: Designing Views 205

Generating column totals, averages, and percents


To display totals, averages, or percents for a columns numeric values, click the Sorting tab of the Column Properties box and select a Totals type other than None. Totals display in blue, unless you change the Column Totals color on the Style tab of the View Properties box. Total calculates a grand total for all main documents and displays this total at the bottom. Average per document calculates an overall average by totaling the main documents and then dividing that value by the number of main documents. For example, if there are four documents and their total is 10, the average per document is 2.5. Average per sub-category calculates an average for each category. Within each subcategory, the documents are summed; that value is divided by the number of documents. Percent of parent category calculates a total for all main documents. For each category, Notes displays the categorys percentage as it relates to the overall view total. Percent of all documents calculates a total for all main documents. For each category, Notes displays the categorys percentage as it relates to the overall view total. You can select Hide detail rows to suppress subtotals for each category and subcategory to display totals without the clutter of extra numbers. Totals calculate only for main documents; response documents are not included. Because column totals recalculate each time you open the view, they may affect database and overall server performance.

206 Application Development with Domino Designer

Table of view, row, and column styles


To make a view attractive and easy-to-use, consider the layout of the view and its columns and rows. View, row, and column properties work together to display colors, widths, fonts, and so on. These options for views, rows, and columns are available in several properties boxes, as noted.
Option name View styles Color: Background Determines the background White, light blue, and color for the view. yellow are good choices. Useful for large views with many categories or topics. Not applicable to calendar views. Description Comments Location

Collapse all when Displays the top-level database is first category in categorized opened views or the main documents in a hierarchical responses view. Users click the category to see individual documents within the category. Row styles Lines per row (1-9)

Determines how many lines Shrink rows to a column can contain. content and Color: Alternate rows are useful accompaniments to multi-line rows. Determines the color for unread documents. Determines the color that alternates with the background color to highlight every other row. Red is used for unread documents in template designs. Useful for multi-line rows. Not applicable to calendar views. continued

Color: Unread rows Color: Alternate rows

Chapter 8: Designing Views 207

Option name Row styles (cont.) Show selection margin

Description Shows the document selection margin. Deselect for cleaner-looking rows.

Comments If you deselect Show selection margin, users can still select documents by pressing and holding SHIFT as they click document names. The selection margin appears temporarily while documents are selected, and hides again when all documents are deselected.

Location

Shrink rows to content

Keeps gaps from appearing below rows that are shorter than the number of lines per row you select. Determines how much More space makes each space there is between rows. row easier to read. Less space condenses the view contents to make it useful for reports or Web users. Shows a green triangle (blue Not applicable to triangle on the Web) next to calendar views. a column that displays categories or response documents. Fills out the last column to avoid empty space in the view. Makes view easier to read. continued

Row spacing (Single, 1-1/4, 1-1/2, 1-3/4, Double)

Show twistie when row is expandable

Extend last column to window width

208 Application Development with Domino Designer

Option name Column styles Column width

Description Determines how many characters fit in one row's column.

Comments (Optional) Select Resizable to allow users to change the width as needed. With the view in Designer, you can also click the column and drag the column divider line to the width you want.

Location

Text style and color: Column title Text style and color: Column values

Determines the font, size, color, and alignment of an individual column title at the top of the view. Determines the font, size, color, and alignment of values that display in this column. The column title and values do not display to users.

Use Apply to All button to change the text style for all titles in the view. Use Apply to All button to change the text style for all columns that display text in the view. Useful for columns used for sorting that contain values users don't need to see. This is not a security feature. Useful for making columns more readable if they contain several values (usually generated by a multi-value field). Beveled--background is gray. Simple--background matches view color.

Hide column

Multi-value separator

For any documents that display multiple values in the column, separates each value with punctuation or a new line.

Show column Shows a bar at the top of the headings view with column titles (Beveled, Simple) with either a beveled or flat look. Lines per heading (1- 5) Color: Column totals

Determines how many lines Useful for long column a column title can wrap. titles or instructions placed in a column title. Determines the color of the total numbers for any columns that contain totals. Calls attention to totals.

Chapter 8: Designing Views 209

Using HTML formatting for views and columns


You can override the default row and column settings for a view by using HTML formatting attributes stored in a column. In Notes, the view still displays as a standard view. On the Web, the view uses the HTML formatting attributes you specify in the column formula. 1. Open the view in Designer and choose Design - View Properties. 2. Click the Advanced tab and select For Web Access: Treat view contents as HTML. 3. Create a column. 4. In the Programmers pane, click Formula and write the HTML code in the Script area. The HTML must define all formatting and document linking for the view.

Default views
A default view is the view users see when they open the database for the first time. Each database has a default view, which appears with an * (asterisk) in the Views list. The default view typically has unrestricted access and contains all documents in the database, sorted by category, by date, or by author. In the Designer templates, the default view usually includes all documents in chronological order and shows main documents associated with responses or supporting documents. To specify the default view, use the option Default when database is first opened in the Options tab of the View Properties box.

Defining what users see when they open views


Several options in the View Properties and Database Properties boxes determine the initial display of a view.

210 Application Development with Domino Designer

Opening to a particular row in the view


To highlight a particular row when a user opens the view, click On Open in the Options tab of the View Properties box and select one of the following from the list: Go to last opened document (the default choice) Go to top row Go to bottom row

Collapsing the view to show only categories


If you have a view that displays categories, you can show the view in collapsed form every time users open it by selecting Collapse all when database is first opened in the Options tab of the View Properties box.

Displaying the last-used view


If you select Restore as last viewed by user (one of the On Database Open choices on the Launch tab of the Database Properties Box), Notes users see the default view the first time they open a database, and thereafter they see the last view they opened. This option isnt available for views opened by Web users.

Page breaks in a view


You cannot set page breaks for a view.

Formulas that look for values in columns and views


Lookup formulas are useful in choice list field formulas to search for values in another database or in the same database.

Referring to views in @function formulas


To refer to a view in an @function formula such as an @DbColumn or @DbLookup, use the actual view name or an alias, in quotes, or use the full cascading name, with an additional \ so that Notes can interpret the cascading name. For example:
"By Author" "View1" "By Author\\Last Name"

Chapter 8: Designing Views 211

Referring to columns in formulas


To refer to a column in an @DbColumn or @DbLookup formula, use the column number, rather than its title. Columns are numbered from left to right: the leftmost column is column number 1. Look at the view in the column builder to make sure you see all its columns. Some columns are not counted in a search, so skip them when youre counting column numbers: Skip any columns that display a constant value. However, if a column contains a formula that happens to return the same result for every document (so that it appears to be a constant value even though it is not), the column does not display a constant value. Include the column in your column count. Skip any columns that consist solely of the following simple Notes functions or @functions: Collapse/Expand (+/-) # in View # of Responses (All Levels) # of Responses (1 Level) @DocChildren @DocDescendants @DocNumber @DocParentNumber @DocSiblings @IsCategory @IsExpandable If you plan to use a lookup formula, such as @DbColumn or @DbLookup, to retrieve data from a view, include a sorted column that the formula can use as the lookup key.

212 Application Development with Domino Designer

Indenting response documents


Indenting response documents beneath main documents is useful when readers want to see the progression of a discussion. You can display 32 levels of responses, with each level indented three spaces under its parent document. The following view in a discussion database displays the threads of a discussion, organized by date.

Such a view requires that: Users have access to response forms, whose types are Response and Response-to-Response. Show response documents in a hierarchy is selected in the Options tab of the View Properties box and the document selection formula uses SELECT @All or contains a formula that allows response documents to be included, such as: SELECT Form = Action Item | @IsResponseDoc The view has a responses-only column. Create the responses column directly to the left of the column under which responses are to be indented. Leave its title blank, make its width 1, and select Show responses only in the Column Info tab of the Column Properties box. Write a column formula that displays information about the response documents shown in the column, such as their authors or creation dates.

Chapter 8: Designing Views 213

Formulas for response columns


Responses-only columns need formulas that generate text summarizing the response documents.

Including information about the author


A discussion database could show the response document author, date, and subject line with the response column formula
From + " added this comment: " + Subject + " (" + @Text(@Created) + ")"

to show a response this way: Stephanie Mahar added this comment: Great job! (10/10/97 04:43:15 PM)

Tracking document status


In an employee information database, a response column could show new employee surveys and exit questionnaires for departing employees as response documents to the regular Employee Record in the Employees by Name view. This formula shows two different messages depending on the form that was used for the response document and also displays the mailing status of the documents.
@If(Form = "Exit"; "Exit Form, "; "New Hire Information, ") + @If(Mailed = "Yes"; "mailed to employee " + @Text(@Date(PostedDate)); "not yet mailed")

If the response uses an Exit form, the response row might look like this: Exit Form, mailed to employee 08/26/97 If the response uses a New Hire Information form, the response row might look like this: New Hire Information, not yet mailed

Tracking the number of responses


You can use @DocDescendants to keep track of numbers of responses, so authors can quickly see how many responses theyve received. This formula for a main document column (not the responses column) is helpful in response-style views.
Subject + " (" + @Name([CN]; From) + @DocDescendants(")"; ", % response)"; ", % responses)")

214 Application Development with Domino Designer

If the document is a main document, the column displays the contents of the Subject field, the author name, and the number of response and response-to-response documents. If there is one response, the column displays response. Otherwise, it displays responses. Main document rows might look like this: Need Help with Trade Show (Indy Montoya, 1 response) Changing the Product Name (Sandy Braun, 2 responses)

Displaying views in Web applications


Views and folders created in Notes may not have as many features on the Web. For example, a view or folder will display as a full screen with default navigation buttons on the Web. To gain more control on the Web, consider creating a view applet, an embedded view or folder, or an embedded view applet. When you embed a view or folder on a form, subform, page, or document, you maintain the same functionality available in Notes applications, and you control the size and appearance of a view or folder display. When you define a view or an embedded view as a view applet, you preserve much of the HTML view functionality and provide features such as resizeable columns, multiple document selection, and scrolling. Embedding a view or folder pane lets you combine views and folders with other form elements (such as styled text) and graphics to create a highimpact design. The Designer templates contain numerous examples of forms designed in this way. If you have multiple views or folder panes you want to display in an application, you can create one or more view templates that control how the embedded objects display. A view template is actually a specially named form that provides the design structure for displaying the embedded folder panes or views in an application.

Chapter 8: Designing Views 215

View applet
You can display a view or an embedded view as a view applet. Here is a view applet on the Web followed by an embedded view applet on the Web:

216 Application Development with Domino Designer

What the view applet does for Web applications With the view applet, Web users can: Resize columns with sliding panes Collapse and expand views without the browser regenerating the page Select multiple documents Scroll vertically to view additional documents in the view Use F9 to refresh the view Use DEL to mark documents for deletion from the database

To display a view applet in a Web application


1. Open a view in Designer. 2. Choose Design - View Properties to open the Property box. 3. Click the Advanced tab. 4. In For Web Access, select Use applet in the browser. When you embed a view in a form, subform, or page, you can display the embedded view as an applet or override the setting when you set properties for the embedded view.

To display an embedded view applet in a Web application:


You can enable an embedded view applet independently of the element it is embedded in. 1. Open a form or page in Designer. 2. Place the cursor where you want the embedded view to display. 3. Choose Create - Embedded element - View and select the view you want to embed. 4. Choose Element - View Properties to open the property box. 5. On the Info tab, specify in the Display drop-down box whether this view should display as an applet by choosing one of the following: Using Java Applet indicates the views setting should be used for this embedded view. Using HTML indicates that the view applet should not be used regardless of the views setting. Using Views display property indicates that the view applet should be used in this embedded view regardless of the views setting.

Chapter 8: Designing Views 217

Font support in the view applet The View applet provides limited support for fonts. Since current versions of the Java Developers Kit (prior to JDK 1.2) provide very limited support for text fonts, mapping between the Designer font set and the font set supported by a specific Web browser is constrained by the JDK supported by a browser. This can sometimes produce inconsistent results across different Web browsers. For best results use one of the following font faces: Courier, Helvetica, or Times Roman. Programming the view applet The View applet is programmable through a number of @commands. These are:
@command ViewCollapse ViewExpand ViewCollapseAll ViewExpandAll ViewRefreshFields Description Collapse the selected document Expand the selected document Collapse all documents Expand all documents Refresh view Upon refresh, the view applet does not delete documents marked for deletion. MoveToTrash EmptyTrash Folder RemoveFromFolder Causes currently selected documents to be marked for deletion Delete documents that are marked for delete Moves or copies the selected documents to a folder Removes the selected document from the current folder

Creating an embedded view or embedded folder pane


When you embed a view or folder pane on a form, subform, page, or document, you maintain much of the view functionality available in Notes applications. Embedding a view or folder lets you control the size and appearance of a view or folder display, especially on the Web.

218 Application Development with Domino Designer

Embedding a view or folder pane lets you combine views and folders with other form elements (such as styled text) and graphics to create a highimpact design. 1. Open a form, subform, or page in Designer, or open a document in Edit mode. 2. Place the cursor where you want the embedded view or folder pane to display. 3. Choose one of the following: Create - Embedded Element - View Create - Embedded Element - Folder Pane 4. (Optional, for views) If you dont want to display the same view in all circumstances, click Choose a View based on a formula. When you click OK to close the dialog box, write a formula in the Programmers pane to display the appropriate view. 5. (Optional) Click the embedded element and choose Element - View Properties (or Element - Folder Pane Properties) to change the alignment or style, or to hide the element under certain conditions. 6. Close and save the form, subform, page, or document. To delete an embedded view or folder pane, click the embedded view or folder pane in the Work pane and choose Edit - Clear. A form can have only one embedded view and one embedded folder pane. Domino disregards the view title and background color of embedded views and uses settings on the Server document to determine the number of lines to display. Domino prevents the view opening if there are create or read access lists on a form in which views are embedded. For compatibility with previous releases, the reserved fields $$ViewBody and $$ViewList still work on forms. An embedded view can be set as an embedded view applet.

Chapter 8: Designing Views 219

Displaying the view navigation bar for embedded views In a Web application, Domino doesnt display the default view navigation bar for embedded views. To give Web users access to navigation functions, use these formulas to add view actions for Next, Prev, Expand, Collapse, and Search:
Action name Next Prev Expand Collapse Search Formula @Command([ViewPageDown]) @Command([ViewPageUp]) @Command([ViewExpandAll]) @Command([ViewCollapseAll]) @Command([ViewShowSearchBar])

Note that these commands do not work if the embedded view is set to display as an applet.

Show single category in embedded views


You can restrict an embedded view to a single category. 1. Open a form in Designer. 2. Choose Create - Embedded Element - View. The Insert Embedded View dialog box appears. 3. Highlight the view you want and click OK. 4. Choose Show Single Category as the event in the Programmers pane. 5. Enter a formula to compute the category. The formula can make use of information about the current user and information from the current document (the one embedding the view). For the Show Single Category option to work, the embedded view must first have been categorized. Note that the category name will not appear in the embedded view. For example, if you check the Show Single Category box for a category named Kitchen, the embedded view will not have a line named Kitchen. Instead, you will see under Kitchen documents such as Stove, Refrigerator, and so on. You cannot use @Commands with Show Single Category. If the Show Single Category formula evaluates to an asterisk (*), all categories are shown. This is useful if, for example, you want to restrict an embedded view to a single category for Web users and show all categories for Notes users.

220 Application Development with Domino Designer

Setting line counts in embedded views


For embedded views, you can specify the number of lines to display in the browser. 1. Create an embedded view in the usual way. 2. In the Info tab of the Embedded View properties box, enter the number of lines next to Lines to display in the browser. If you check Default, the embedded view acts in the same way it did in previous releases, so that the line count value is controlled server-wide from the NOTES.INI file. Note that the line count property is ignored if you choose a view applet to display the embedded view. In the Web server, you can determine the number of lines displayed by looking (in order) at the following sources: If the URL contains a &Count argument, use that number. If there is no &Count argument, look at the number specified in the embedded view properties box. If no number is specified in the embedded view properties box, use the server-wide default for the number of lines.

Hiding a view
Designer includes several ways to hide a view from users.

Hiding a view from Notes users


Deselect Show in View menu on the Options tab of the View Properties box. Omitting a view from the View menu applies only to Notes users, since Web users dont have access to Notes menus. Open the design toolbox, click the view name in the right pane, and choose Design - Design Properties. Select Hide design element from Notes R4.6 or later clients. Hiding a view from Notes clients is useful when you have a Web-only view or when you want to remove the view from both the View menu and the folders pane. Give the view a name and surround it with parentheses for example, (All).

Chapter 8: Designing Views 221

Hiding a view from Web users


Open the design toolbox, click the view name in the right pane, and choose Design - Design Properties. Select Hide design element from Web clients. Hiding a view from Web clients is useful when you have a Notes-only view, or when you want to remove the view from the folders pane and the Open Database Views list. Give the view a name and surround it with parentheses for example, (All).

Showing a view only to users of older Notes releases


When you have a view tailored to users of older Notes releases, open the Designer and click the view name. Choose Design - Design Properties. Click the Design tab and select Do not show this design element in menus of Notes R4 or later clients. The view doesnt appear to anyone using Notes Release 4.0 or later.

Identifying unread documents


To help users find new or modified documents, display the unread mark (an asterisk) next to unread documents in the view. A set of unread marks are maintained for each user, so even if one person has read a particular document, the asterisk still appears for other users who havent read it yet.

Choosing a style for unread marks


These options are set as a design property for a view. Open the Advanced tab of the View Properties box, and Select an Unread marks option. You can display unread marks as: Standard (compute in hierarchy) Displays asterisks for unread main documents and response documents and for any collapsed categories containing unread main or response documents. Unread Documents Only Displays asterisks only for unread main or response documents. Unread marks do not appear next to collapsed categories. This choice displays the view faster than the Standard display and is a good compromise between showing unread marks at every level and not showing them at all.

222 Application Development with Domino Designer

Choosing the option None omits unread marks. Users can still navigate to the next unread document by using SmartIcons.

Choosing a color for unread marks


To change the color of unread documents in the view from the default color red, click the Style tab of the View Properties box and select another color for Unread rows.

Disabling unread marks for modified documents


If the unread status of modified documents is unimportant to users or if the database resides on a server that users dont access directly, turn off unread tracking for all documents in a database to conserve disk processing time. Open the Design tab of the Database Properties box and select Do not mark modified documents as unread. This setting affects all views in the database. Users see only new documents as unread; modified documents do not appear as unread.

Formatting date and time columns


To format values that result in a time or date displaying in a column. select the Data and Time Format tab of the Column Properties box. You have the following choices:
Option name Show Selections Date and time Date only Time only 'Today and time Date format month/day month/year month/day/year Time format hour:minute hour:minute:second Description Today and time shows values resulting in the current date with the word Today. Values resulting in the previous day display Yesterday. All other values display the date. If you have an international date format set in your operating system, these choices change. For example, they may change from month/day to day/month. If you have an international time format set in your operating system, these choices change, for example, from 02:30 to 14:30. continued

Chapter 8: Designing Views 223

Option name Time zone

Selections Adjust time to local zone

Description Adjust time to local zone displays the time relative to the time zone of the reader. A document created at 3:00 P.M. in New York that is read by a user in Los Angeles adjusts to Pacific Standard Time; the creation time is displayed as 12:00 P.M. Always show time zone displays the time zone where the document was created. With this option, the creator's time zone is always shown. If a document is created in New York at 3:00 P.M., a user in Los Angeles sees the creation time as 3:00 PM EST. A user in New York also sees the creation time as 3:00 PM EST. Show only if zone not local displays the time zone where the document was created only when the document is read by someone in a different time zone. A document created in New York at 3:00 P.M. displays to all users in the U.S. Eastern standard time zone as 3:00 PM. Users in all other time zones see the creation date as 3:00 PM EST.

Always show time zone

Show only if zone not local

Displaying numbers in columns


To format values that result in a number displaying in the column, select a style in the Numbers tab of the Column Properties box. General formatting displays numbers as they are entered; zeroes to the right of the decimal point are suppressed. For example, 6.00 displays as 6. Fixed formatting displays numbers with a fixed number of decimal places. For example, 6 displays as 6.00. Scientific formatting displays numbers using exponential notation; for example, 10,000 displays as 1.00E+04. Currency formatting displays values with a currency symbol and two digits after the decimal symbol; for example, $15.00. The currency symbol and thousands separator displayed are based on settings in your operating system.
224 Application Development with Domino Designer

Additional formatting options


For any formatting type other than General, select a number from 1 to 15 from the Decimal places list. Select Percentage (value * 100)% to display values as percentages; for example, to display .10 as 10%. Select Parentheses on negative numbers to display negative numbers enclosed in parentheses; for example, (5) instead of -5. Select Punctuated at thousands to display large numbers with the thousands separator; for example, 1,000 in English, or 1.000 in French.

Refreshing view indexes


A view index is an internal filing system that builds a list of documents that belong in a view. When users add or change documents, the view index must be refreshed to show them which documents are new or changed. Refreshing a view index can occur manually when users press F9, as part of a condition built into the view design, or as part of the Updall (Update ALL) server process set up by the server administrator.

Refresh time options


To determine when to refresh an individual view, select a Refresh index option from the Advanced tab of the View Properties box. Auto, after first use Updates the view every time a user opens a view after the first time. Automatic Updates the view whether or not users ever open the database. Using this option, views open more quickly. Manual Relies on the user to refresh the view. This option is useful for large databases that dont need to stay up-to-date. Using this option, views open very quickly. Users just press F9 to refresh the view. Auto, at most every n hours Controls how frequently the view index updates. Choose this option for large databases that change fairly often. The view index updates automatically no more frequently than the specified interval. When a user opens a database in which changes have been made since the last indexing, the refresh icon appears, and the user can press F9 to refresh the view manually.
Chapter 8: Designing Views 225

If the document-selection formula is time-based, refresh the index as often as new documents are added. For example, if the view selects documents once a day, select Auto, at most once every 24 hours, to refresh the view index once daily.

Refresh display options


The On Refresh options (on the Options tab of the View Properties box) determine how users see the changes in a view. Choices are: Display indicator Does not show view changes automatically. Instead, the refresh icon in the left corner of the view displays to indicate that the view has changes and users must click the icon to see any changes. Refresh display Refreshes the display automatically before showing the view to users. Refresh display from top row Updates the view from the top down. This is useful in a reverse chronological display where users are likely to look for changes at the top of the view first. Refresh display from bottom row Updates the view from the bottom up. This is useful in a chronological display where users are likely to look for changes at the bottom of the view first.

Discard index options


To delete indexes automatically for a particular view and save disk space, specify a Discard index option from the Advanced tab of the View Properties box. When users open a view whose index has been discarded, they may have to wait for Domino to recreate a view index. These settingsoverride the NOTES.INI setting Default_Index_Lifetime_Days, which the server administrator sets and which, by default, deletes view indexes after 45 days. After each use Deletes the view index as soon as the user closes the database. This option saves the most disk space, but the index must be rebuilt the next time the view is opened. Choose this option for views that are used infrequently, but on a predictable basis for example, a view that an agent opens only on Friday afternoons. If inactive for n days Deletes a view index if the view hasnt been used in a specified number of days. Domino rebuilds the view index the next time a user opens the
226 Application Development with Domino Designer

database. (This option doesnt affect local databases.) Choose this option for databases that users infrequently or unpredictably need. Never Permanently preserves the view index and appends updates to the existing index. Because this option takes up more disk space than the other options, use this only for views that users frequently need, so they dont have to wait for a new view index to be created when they open the database. When the view index is deleted The Updall (Update All) server task, which runs by default on each server at 2 AM, deletes the view index. Domino deletes the index the first time Updall runs after the index becomes eligible for deletion. For example, if you select After each use and the view is used at 10 AM Tuesday, the index is not actually discarded until 2 AM Wednesday. If you choose to delete the index after one day, Domino waits until the index is at least one day (24 hours) old before deleting it. If the view is used at 10 AM Tuesday, it is only 16 hours old at 2 AM Wednesday when Updall runs, so it is not deleted until the next time Updall runs at 2 AM Thursday. For more information, see Administering the Domino System.

Designing folders
Folders are containers used to store related documents or groupings of documents. Folders have the same design elements as views. You can design folders in much the same way as views, using the Create - Design Folder command. The difference between folders and views is that views always have a document selection formula that collects and displays documents automatically. A folder remains empty until users or programs add documents to the folder. Note that Web users cannot drag documents into folders. For more information on folders, see Notes Help.

Chapter 8: Designing Views 227

Designing a form as a view or navigator template


In Web applications, to create an association between a form and a view or navigator, you can assign a reserved name to the form. Domino uses the form as a template when users open the view or navigator. This can be a good way to create a standard display for views and navigators in your site. Use the following reserved form names to create an association between a form and a view or navigator. Note that Domino requires an embedded view or the $$ViewBody field on the form, but ignores the value.
Form name $$ViewTemplate for viewname Design element required Comments Embedded view or $$ViewBody field Associates the form with a specific view. The form name includes viewname, which is the alias for the view or when no alias exists, the name of the view. Associates the form with a specific navigator. The form name includes navigatorname, which is the navigator name. For example, the form named $$NavigatorTemplate for World Map associates the form with the World Map navigator. Domino ignores create and read access lists on the form. $$ViewTemplateDefault Embedded view or $$ViewBody field $$NavigatorTemplate Default Embedded navigator or $$NavigatorBody field Makes this form the template for all Web views that arent associated with another form. Makes this form the template for all Web navigators that arent associated with another form.

$$NavigatorTemplate for navigatorname

Embedded navigator or $$NavigatorBody field

228 Application Development with Domino Designer

Chapter 9 Designing Navigators


This chapter explains how to create graphical navigators that help users find documents and use the database.

Navigators
Navigators are graphics that include programmed areas that direct uses to specific parts of a database. They let users find documents or take actions without having to open views. If you are designing a navigator for the Web, consider either embedding a navigator or importing a navigator into a form, subform, page, or document. Navigators usually include hotspots; that is, programmed areas that users click to execute an action. A hotspot can be text, graphics, or a combination of both. If you use navigators in an application, you usually want the navigator to display automatically when the application opens. To use a navigator in a Web application, you must select Web browser compatible as a navigator property. With this setting on, Domino converts a navigator to an HTML imagemap. Navigators on the Web always display as full-screen imagemaps. To control the size and display of a navigator on the Web, you can embed a navigator in a form. If your navigator inherits its design from a template, do not make any changes to the design of your navigator, since any changes you make will be over-written by the template.

Navigator objects
You create a navigator by combining navigator objects. Navigator objects include graphic backgrounds, hotspot rectangles, hotspot polygons, hotspot circles, graphic buttons, buttons, text, rectangles, rounded rectangles, ellipses, polygons, and polylines. To create navigator objects, you can import or paste objects from another application or you can use the drawing tools Designer supplies. The drawing tools include hotspot tools that you use to define a clickable area in a navigator.

229

All navigator objects except polylines behave the same on the Web as they do in Notes. Polyline objects display on the Web, but clicking them has no effect.

Navigator actions
You can add actions to all navigator objects except those pasted or imported as graphic backgrounds. Designer provides the following simple actions that you can attach to navigator objects: Open another navigator. Open a view or folder. Serve as an alias for a folder. Clicking the object displays the contents of the designated folder in the view pane. Open a database, view, or document link. Open a URL. To create more complex flexible actions use @function formulas or a LotusScript program. LotusScript programs can perform tasks that arent possible with @function formulas; for example, manipulating a database ACL. For more information on writing formulas and scripts for buttons and hotspots, see the Programming Guide.

Creating a navigator
If you cant copy and paste a navigator that is similar to the one you need, create a new navigator. 1. Open a database in Designer. 2. Select Navigators in the Design pane. 3. Click the New Navigator button above the Work pane. 4. Choose Design - Navigator Properties. 5. Give the navigator a name that describes its use. 6. To use the navigator in a Web application, check Web browser compatible. 7. (Optional) Choose an initial view or folder to open along with the navigator.

230 Application Development with Domino Designer

8. (Optional) Select Auto adjust panes at runtime so that users wont have to manually resize a navigator that doesnt fit a window. 9. Click the navigator window. 10. Use the Create menu or the SmartIcons bar to draw objects or paste objects from the clipboard. 11. Click each object and choose Design - Object Properties to assign a name and style. 12. In the Programmers pane, select a Run option and assign actions to each object. Run options specify what happens when users click the object. Select Simple action to choose a predefined automation, such as Open a View. Select Formula to define an action using the formula language. Select Script to define an action using LotusScript. 13. Close and save the navigator. Editing a navigator To edit an existing navigator, open the navigator in Designer. Choose Design - Navigator Properties and make changes as needed. To change any object, click on the object, select Design - Object Properties, and make changes as needed.

Adding graphic objects to navigators


You can create graphic objects in another product, such as a drawing, charting, or mapping package, and import or paste the objects into a navigator as a graphic background for the whole navigator or as a button that you automate with an action. A navigator can have only one background graphic, but it can have many buttons. Designer includes a set of drawing tools, available on the SmartIcons bar or on the Create menu, that you can use to create or enhance graphic components of a navigator. The drawing tools are displayed in the SmartIcons bar when the navigator is in Designer. Note that you cannot click polylines on the Web, even though they display on the Web.

Chapter 9: Designing Navigators 231

Adding and enhancing graphics in a navigator


The following types of files can be pasted or imported into a navigator: Bitmap (BMP) GIF JPEG PCX TIFF 5.0s Note Graphic backgrounds cannot be moved; graphic buttons can be moved. To paste a graphic from another product 1. Copy the graphic to the clipboard. 2. Open the database in Designer. 3. In the Design pane, click Navigators. 4. In the Work pane, double-click the name of the navigator you want to open. 5. If you are pasting in a graphic button, move the cursor where you want to place the graphic button. 6. Choose one of the following: Create - Graphic Button to paste the graphic as a button on the navigator. Create - Graphic Background to paste the graphic as a background for the navigator. To import a graphic 1. Create a new navigator, or open an existing navigator in Designer. 2. Choose File - Import. 3. Select the file to import and click OK. 4. Click Graphic Button to import the graphic as a button, or click Graphic Background to import the graphic as a background for the navigator. To edit a graphic Double-click a drawn object to edit its properties. For example, you can change colors or widths of lines on drawn objects. Use drawing tools available from the Create menu or the SmartIcons bar to enhance existing objects. To edit an object that is under another object, click the overlying object and choose Design - Send to Back and then select the object you want to edit. Hotspots are always on top and cannot be sent to the back.
232 Application Development with Domino Designer

To delete a navigator object To delete a navigator object (such as a button or a rectangle), select the object and choose Edit - Clear. To remove a graphic, choose Design - Remove Graphic Background. Tips for drawing new navigator objects To create several identical navigator objects quickly, hold the SHIFT key down while choosing Create. Draw all the objects you need; choose Create - <shape name> to exit creation mode. To draw a square or a circle, hold the SHIFT key down while dragging the shape. To move an object that isnt locked into position, drag the object to a new location. To resize an object, click the object, position the cursor on one of the sizing corners, and drag the object to the size you want. To line up objects at a grid mark, choose Design - Navigator Properties, click the Grid tab, and select Snap to grid. Choose a grid size (1 pixel is the most precise). To freeze an object at its current position and size, click the object, choose Design - Object Properties, and select Lock size and position.

Adding text to and highlighting a navigator object


You can add text to most objects, including buttons, rectangles, polygons, and so on. You cannot add text to the following objects: polylines, hotspot rectangles, hotspot polygons, graphic buttons, and graphic backgrounds. You can also highlight an object. When an object is highlighted, its appearance changes when the cursor is over it or when it is clicked. 1. Open the database in Designer. 2. In the Design pane, click Navigators. 3. Double-click the navigator name in the Work pane. 4. Click a navigator object. 5. Choose Design - Object Properties. 6. To add text to the object, enter text into the Caption box at the Info tab. 7. To define highlighting for an object, click the HiLite tab. Select Highlight when touched to show the highlighted style when the users cursor passes over the object. Select Highlight when clicked to show the highlighted style when the user clicks the object. The object remains highlighted until the user clicks another.
Chapter 9: Designing Navigators 233

8. (Optional) Change the highlight border width, highlight border color, and highlight background color. 9. (Optional) Click the Styles tab and do one of the following to define the unhighlighted style: Select a border width, border color, and background color. For a button, select a button face color, bevel width, and border color. Select Make Default to apply to all new objects of this type. 10. Close and save the navigator. Tip Choose Design - Preview in Notes or Design - Preview in Web browser to enter testing mode and check the highlight settings.

Adding hotspots to navigators


A hotspot is a programmed area that you click to execute an action. Hotspots are always topmost on a navigator you cannot send them to the back. To automate a hotspot, attach an action to it. For example, if your navigator is a map, you can create hotspots so that a user clicking on a region in the map views information about that region. To create a hotspot 1. Open a navigator in Designer. 2. Select a hotspot tool from the SmartIcons palette. 3. Click on the navigator and drag to create the hotspot. The polygon tool allows you to create a line segment each time you click. Double-click to complete the drawing and close the polygon hotspot. 4. (Optional) Double-click the hotspot to edit its properties.

Automating navigators
After you add objects to a navigator, you automate the objects by attaching actions to them. For example, to program a graphic button so that it opens a particular view when a user clicks it, select Run: Simple Actions and then choose Open a view or folder in the Action field of the Programmers pane. Then select a particular view in the Programmers pane.

234 Application Development with Domino Designer

Simple actions for navigators


Action: Open a view of folder When users click an object that opens a view or folder, the preview pane (if it is open) changes to display the selected document in the new view or folder. Action: Alias a folder When users click an object that activates a folder, the folder activated by that object replaces the current folder (if one is open). To return to the original folder, use View - Go To. Action: Open another navigator When users click this object, the current navigator (if there is one) is replaced by the new navigator. The replacement navigator must be from the same database. Action: Open a link The action prompts you to paste a link to a document, view, or database. When a user clicks this type of object, Designer presents the specified document, view, or database. Action: Open URL The action prompts you to specify a URL to open. Clicking the navigator object opens the URL. Custom actions You can use an @function formula or a LotusScript program to define a custom action. A navigator that runs an @function formula allows you to create specialized actions that arent related to switching to a view, a folder, a navigator, or a link.

To attach an action
1. Open the database in Designer. 2. In the Design pane, click Navigators. 3. In the Work pane, double-click the name of the navigator you want to edit. 4. Select a navigator object. 5. In the Programmers pane, click Run: Simple action(s). 6. Select the simple action to run and supply any required information. 7. Close and save the navigator.

Chapter 9: Designing Navigators 235

To attach a formula or script


1. Open the navigator in Designer. 2. Select the navigator object. 3. To add a formula, select Run: Formula in the Programmers pane. 4. Type the formula and click the green check mark to confirm it. 5. To add a script, select Run: LotusScript in the Programmers pane. 6. Write the LotusScript program. 7. Close and save the navigator. For more information on writing formulas and scripts for buttons and hotspots, see the Programming Guide. Examples: Automating a navigator Opening a view A navigator that switches to another view gives users a graphical way to choose a view so they dont need to know the name of a view in the view pane. The Main Navigator in the Discussion template uses objects to open these views: All Documents, By Category, and By Author. Creating a navigator object that opens a navigator A navigator object (such as a button) that switches to another navigator is a graphical way to guide users through a series of decisions to reach the information they need. This navigator displays a bar chart created in 1-2-3.

236 Application Development with Domino Designer

To find out more information, users click a bar that represents an areas sales. Each bar in the first navigator is a hotspot rectangle that takes users to the Weekly Details by Country navigator. When users reach the second navigator, they see another bar chart that displays weekly sales by individual country. Clicking a bar in this chart opens the view for the country (for example, View by country\France). Each bar in the second navigator is a hotspot rectangle whose Open a view or folder action specifies the appropriate country view.

Creating a shortcut navigator with an @function formula This shortcut navigator allows users to click the icon instead of using the Create menu to create a new Action Item document.

The action for the icon is Run a formula with the formula:
@Command([Compose];"";"3. Action Item")

Making a navigator object that runs a LotusScript program When users double-click the navigator object (for example, a button), this script opens the current database:
Sub Initialize Dim session As New NotesSession Dim db As NotesDatabase Set db = session.CurrentDatabase Call db.Open("", "") Messagebox(db.Title & " " & db.FileName) If db.IsOpen = True Then msg$ = "open" Else msg$ = "closed" Messagebox("Database is " & msg$) End Sub

Chapter 9: Designing Navigators 237

Navigators, imagemaps, and outlines


Navigators are similar to imagemaps and outlines. Depending on the situation, you may want to use an imagemap or outline instead of a navigator. A navigator is a graphical roadmap that directs users to specific parts of an application. A navigator like a form, a page, or a view is an independent design element. It is a powerful tool for combining graphics, text, and action buttons. Navigators can also be embedded in a form or a page. Embedded navigators have the advantages of combining a navigator with other form or page elements and of letting you design a navigator template to establish a uniform way of presenting navigators in an application. One disadvantage of navigators is that once you design a navigator, it is usually static and can be difficult to change. An imagemap is a graphic you enhance with programmable hotspots. Unlike a navigator, an imagemap can reside only on a form or a page. You can easily combine an imagemap with text and other form or page elements. You can also control the display of an imagemap using a hide-when or computed-for-display formula. For most situations, an imagemap provides all the functionality you need to create a great-looking navigational structure for your application, but if you plan to combine a number of graphics and buttons, you might consider creating a navigator instead. An outline lets you create an organizing structure for an application and gives you control over how elements display in a navigation pane. An outline also gives you the power to create a sophisticated site map that combines text, graphics, and automation, and lets you combine database elements with links to Web sites and to pages, documents, or views in other databases. Because an outline is created from the contents of the database, it is easier to maintain than a navigator and is more flexible.

238 Application Development with Domino Designer

Displaying a navigator when users open a database


When users open a database, the navigator can display in the Navigator pane or in a full-screen window. For example, the interface to an online help system might be a full-screen navigator. If you set up the database to open a navigator, the initial view of that navigator overrides the default view or the current view for the database. 1. Select the database that contains the navigator you want to display and choose File - Database - Properties. 2. Click the Launch tab. To display the navigator in a navigation pane, select On Database Open: Open designated Navigator. To display the navigator in a full-screen window, select On Database Open: Open designated Navigator in its own window. 3. Select the navigator. The Open designated navigator in its own window property causes the chosen navigator to display as a full screen. The regular navigation, view, and preview panes are not available from a full-screen navigator, but users can choose View - <view name> to return to a specific view.

Hiding navigators
Designer includes several ways to hide a navigator from users. There may be times when you want to present one navigator to Notes users and another to Web browser users. Hiding a navigator from Notes users Open a database in Designer and click Navigators in the Design pane. Highlight a navigator name in the Work pane and choose Design Design Properties. Click the Design tab and select Hide design element from Notes R4.6 or later clients. Hiding a navigator from Web users Open a database in Designer and click Navigators in the Design pane. Highlight a navigator name in the Work pane and choose Design Design Properties. Click the Design tab and select Hide design element from Web clients.

Chapter 9: Designing Navigators 239

Showing a view only to users of older Notes releases When you have a navigator tailored to users of older Notes releases, open the database in Designer, click Navigators in the Design pane, highlight a navigator name in the Work pane, and choose Design - Design Properties. Click the Design tab and select Do not show this design element in menus of Notes R4 or later clients. The navigator doesnt appear to anyone using Notes Release 4.0 or higher.

Embedding navigators in a form, subform, page, or document


Embedding a navigator in a form, subform, page, or document gives you greater control over the display of a navigator on the Web. It also allows you to combine the navigator in the same window with other objects.

To embed a navigator in a form, subform, page, or document


1. Open a form or page in Designer or open a document in Edit mode. 2. Place the cursor where you want the embedded element to display. 3. Choose Create - Embedded Element - Navigator. The Insert Navigator dialog box appears. 4. Select a navigator to embed. 5. (Optional) If you dont want to display the same navigator in all circumstances, click Choose a Navigator based on a formula in the Insert Navigator dialog box. When you click OK to close the dialog box, write a formula in the design pane to display the appropriate navigator. 6. (Optional) Click the embedded element and choose Element Navigator Properties. The Embedded Navigator Properties box appears. You can then change the alignment or style, or hide the element under certain conditions. 7. Close and save the form, subform, page, or document. To change the navigator, click the embedded navigator and choose another from the list in the Programmers pane. You can embed multiple navigators anywhere on a form, subform, page, or document, including in tables, as part of collapsed sections, and as left-, right-, or center-aligned design elements. Avoid hiding embedded navigators with the Hide design element from Web browsers option. Forms with hidden navigators wont display on the Web.

240 Application Development with Domino Designer

To delete an embedded navigator


To delete an embedded navigator, click it and choose Edit - Clear.

$$ Fields
For compatibility with previous releases, the reserved field $$NavigatorBody still works on forms. It duplicates functionality now provided by embedding.

Overriding an embedded navigator with a navigator template


A navigator template is a navigator that has the name $$NavigatorTemplate for <navigator name>. In a Web application, when you embed multiple navigators on a form or page, Domino displays the navigator that was named in the form or page name in every embedded navigator. To override this behavior, designate only one embedded navigator as the one to reference the form name navigator or page name navigator and ignore its original value. There is no equivalent procedure for $$NavigatorBody fields. 1. Select the embedded navigator and choose Element - Navigator Properties. The Embedded Navigator Properties box appears. 2. Click the Info tab and select Display navigator specified in form name when this form is used as a Navigator Template.

Importing a navigator into a form, subform, page, or document


When you import a navigator into a form, subform, page, or document, a composite image of the navigator is pasted in. The imported navigator actually becomes a picture object so that you make all future changes to the picture object. The navigator text boxes, graphic buttons, polygons, and other navigator objects are converted to imagemap hotspots on the newly created picture object. An advantage of importing a navigator is that formulas and LotusScript that were originally attached to navigator objects become attached to the imagemap hotspots. Imported navigators, unlike navigators and embedded navigators, allow you to make changes to the formulas and the LotusScript. An imported navigator, unlike an embedded navigator, has no links to the original navigator. Note that you can import only navigators that are Web-browser compatible. Check the Web browser compatible box at the Info tab of the Navigator Properties box for the navigator you want to import.

Chapter 9: Designing Navigators 241

When you import a navigator, navigator simple actions are converted to equivalent hotspots:
Navigator Simple Action Open another Navigator Open a View or Folder Alias a Folder Open a Link Open URL Hotspot equivalent @Command([OpenNavigator];NavigatorName) @Command([OpenView];ViewOrFolderName) @Command([OpenView];FolderName) Resource link of type link Resource link of type URL

To import a navigator into a form, subform, page, or document


1. Open a form, subform, or page in Designer or open a document in Edit mode. 2. Place the cursor where you want the imported navigator to display. 3. Choose Create - Embedded Element - Import Navigator. The Import Navigator dialog box appears. 4. Select the navigator to import. Note that the navigator you select must already be saved as Web browser compatible. 5. Close and save the form, subform, page, or document.

Testing navigators
To test a navigator while you design it, switch to testing mode to see a message describing what happens if the simple action, formula, or script runs. For navigators that perform multiple steps or complex tasks, split the process into several small tasks and create an action for each. Test and fix each small task first. When everything is working correctly, combine the formulas into one, and then test the automation again by creating a sample copy of the database and testing all navigator behavior. To test a navigator, follow these steps: 1. Open the database in Designer. 2. In the Design pane, click Navigators. 3. In the Work pane, double-click the navigator you want to open. 4. Choose Design - Preview in Notes or Design - Preview in Web Browser <Web browser>.
242 Application Development with Domino Designer

5. Highlight and click each object to see if the highlighting and actions are as you expected. You can preview in either Notes or a Browser to see how the action actually performs. 6. If the test produces unexpected results, close the previewed item and use the Windows taskbar to return to Designer. 7. Correct the problems and run the test again. 8. When the test shows no problems, close and save the navigator.

Chapter 9: Designing Navigators 243

Chapter 10 Automation in Applications


This chapter explains how to add automation features to an application to make it easier to perform tasks in the background.

Automation
Automation in an application speeds up repetitive tasks, handles workflow, updates information, performs calculations, runs programs, and checks for errors. You can add automated components to most design elements in a Domino application: a database, a page, a frameset, a view, a form, or a document. The automated components include: Actions Use an action with a form or view to set up a user-activated task. You can make the action available in the Actions menu or as a button in the action bar. In particular, use actions to simulate Notes menu items for Web browser users. Then, those users can complete Notes tasks when accessing Domino databases. Hotspots Use a hotspot in a form or document to set up a user-activated task. The hotspot can be a link to another Web site, database, or element in a database; a button; a pop-up; or an action. Agents Use agents to set up user-activated tasks, or background tasks, in any part of a Domino application. Agents can be simple, such as moving documents to a folder, or complex, using Java programs to run multiple automated tasks at scheduled times. Agents are stored with databases, but you can use them to run automated tasks for views, documents, fields, and databases. Programs that are activated by an event Associate an automated task with an event that occurs when a design element is used. For example, set up an error-checking automated task to verify user input after a user has saved a document.
245

To set up the tasks associated with these automated components, use the following: Simple actions You can add automation to design elements without knowing a programming language. You can select one or more simple actions from a list. Simple actions cant be customized and are not supported in Web applications. Formulas You can write an @function formula that runs by itself or with a simple action. You cannot combine an @function formula with a LotusScript program. LotusScript LotusScript is a complete scripting language that can support most application-wide tasks. JavaScript Use JavaScript with agents and events to efficiently interact with the user for tasks such as form and field validation and simulating dialog boxes. Java You can write Java programs or import Java files into agents.

Actions
Create an unshared action in a view or form to provide one-click shortcuts for routine tasks in a view or in a document created with the form. Actions are part of a view or forms design and are not stored with individual documents. You can also create a shared action in a database that can be used in several forms and views. A shared action is stored as a resource with the database. To build an action, you can use any of the following: Simple actions that you select from a list Formulas LotusScript JavaScript

246 Application Development with Domino Designer

When to use actions Because actions are available in a view or document, use them for any general-purpose task related to a group of documents. For example, use actions: When Web browsers accessing the database need substitutes for Notes menu choices. To present a shortcut as a clickable button. When the automated task is relevant only to a subset of documents. When users need to see all the available choices in a row at the top of a document. When the automated task isnt limited to a particular section of a form. If formulas are complex and you dont want to save the formula with each document. Examples of actions View actions Let users create, print, delete, or categorize documents. Form actions Process an approval; mail a document; or give Web users, who dont have access to Notes menus, a way to click to edit, save, or close documents. Simulate Notes menus for Web users. Automatically send documents to reviewers. Automatically process employee requests. Notes on actions Some views and forms in databases contain built-in actions, available either in the Actions menu, as buttons, or both. You cant change the built-in actions or properties, but you can customize their appearance. Launch Designer and open the view or form. Click Objects and the built-in actions are displayed in the list.

Hotspots
Hotspots are associated with text or an image in the body of a document and can complete any of these types of automated tasks: Link Open a Web site, a database, or an element in a database (a page, view, frameset, form, document, folder, or navigator). Text pop-up Display information in a pop-up.
Chapter 10: Automation in Applications 247

Button Complete a programmed task, using simple actions you select from a list, formulas, LotusScript or JavaScript. Formula pop-up Complete a programmed task using only formulas, with the results displayed in the pop-up. Action hotspot Complete a programmed task, using simple actions you select from a list, formulas, LotusScript, or JavaScript. When to use hotspots Create a hotspot in a document when the hotspot is specific to the document. Create a hotspot in the a form when every document using that form needs the hotspot. Examples of hotspots Use a document or database link to provide a cross-reference for more information that is stored in a document in other database. Use a URL link to cross-reference a Web site for downloading software. Use a text pop-up to provide help information about what values to specify in a field. Use a button to submit a completed document for processing or add a database to a users workspace

Agents
Agents are stand-alone programs that perform a specific task in one or more databases. Agents are the most flexible type of automation because: They can be run by users in the foreground or run automatically in the background as scheduled agents. They arent associated with a specific design element. They can be run on a specific server, on several servers, on workstations, or the Web. They can call other agents. They can consist of simple actions, formulas, LotusScript, or Java programs.

248 Application Development with Domino Designer

They can be distributed easily because they can be replicated. They can be personal or shared. A personal agent is created and run by the same user. No one else can run a personal agent. A shared agent is created by one user and can be run by other users. Because agents are so flexible and powerful, you might consider their characteristics first to decide the type of agent you want to build, and then build it. The Agent Manager supports all aspects of building, running, and troubleshooting agents. The Agent Manager checks security, manages agent scheduling, monitors events and starts the appropriate agents when their associated events occur, records information in a log (the Agent Log), and performs database operations to run the automated tasks associated with the agent. Although you dont work directly with the Agent Manager, you use its components for building and troubleshooting an agent. When to use agents Use agents for database-wide and domain-wide automated tasks and for complicated automated tasks. You can use them to easily access, process, and manage data on other servers or in other databases. See Agents to run before Web users access Domino for an example. Notes on agents Some databases and templates have built-in agents. For example, the mail template has several built-in agents that let users manage their messages and customize their mail databases. To see the agents in a database, select the database and choose View Agents.

Events
When users work in Domino design elements, Domino tracks their operations as events (for example, opening a database, opening a view, opening a document). You can attach programming tasks to these events. To build a program for an event, you can use: Formulas LotusScript JavaScript

Chapter 10: Automation in Applications 249

When to use event programming


Use event programming to run tasks that users shouldnt have to activate themselves and that are very specific. Event programming is particularly useful when the timing of the program must be precise or the tasks are associated with a particular design element. For a table of events that can be automated, see Event Descriptions in Volume 1 of the Programming Guide. Examples of event programming Error checking when a user completes a field or closes a document Recalculating fields when a user saves a document Prohibiting certain actions in a document Prompting for user input Displaying information when a user clicks a button

Types of events
Every design element has events that you can program, but they vary according to the design element. In the Programmers pane, click the Objects tab to review the events you can program.

Database events
Database events pinpoint database-wide activities such as opening and closing a database and deleting and undeleting documents. Examples PostOpen open a specific view to direct users to action items QueryDocumentDelete prevent users from deleting a particular document when the value of a status field on an action item is Open PostDocumentDelete archive a deleted document QueryClose prevent users from closing a database when there are still action items in the action item view assigned to them

View events
View events occur when users work in a specific view or folder. View events include opening or closing a view, adding documents to a calendar view, or adding documents to a folder. Examples QueryOpen prevent users from opening a view in certain circumstances such as from opening a month end view before the twentieth day of the month
250 Application Development with Domino Designer

PostOpen create a new document or open an existing one QueryRecalc inform users before a large view refreshes that it could take a while and ask them if they really want to proceed QueryPaste prevent users from pasting documents into the database PostPaste change the value of StartDateTime and EndDateTime in the document when you paste an appointment on a particular day and time slot. QueryClose prevent users from closing a view such as when there are still action items in the action item view assigned to them In addition to the events available for all views, calendar views have specific events. Examples RegionDoubleClick create a new document when users click an area in a calendar view QueryDragDrop prevent someone from dropping an appointment on an inappropriate day or time, such as a weekend day or a time that is after 5 PM PostDragDrop change the value of StartDateTime and EndDateTime in the document after you drop an appointment on a particular day and time slot

Folder events
In addition to the events available for all views, folders also have QueryAddToFolder. You could program the QueryAddToFolder event to prevent someone from dragging a document from one folder to another. For example, you can prevent documents from moving to the Done folder if their status is still Open.

Form events
Form events occur at the document level when users open or close a document. They are useful for speeding up document display times because they execute only when a specific form event occurs, unlike field recalculations that occur each time a document is saved, opened, or refreshed. Examples Initialize load an additional program before a document displays. QueryClose check for errors and validate fields before closing a document.
Chapter 10: Automation in Applications 251

QuerySave reset a field value when users save documents rather than using conditional formulas in the field itself. For example, to reset the status field if the document is being saved, create a script for a QuerySave event rather than include a formula that uses @If(@IsDocBeingSaved;x;y). With QuerySave, you can also execute processing logic and avoid the unnecessary recalculations inherent in computed fields. For example, you have a form with a hidden computed field called State that determines where documents are in the workflow and where they need to be sent. By replacing the field formula with a LotusScript program that sets a field value during the QuerySave form event, set the field value in the document only when it is saved, not when it is opened or refreshed.

Field events
Field events capture users movements into or away from a field. Examples Entering refresh hide-when formulas Exiting guide users to a certain field Exiting verify that users supplied valid information

Click events
The Click event occurs when users click actions or hotspots, or choose tasks from the Actions menu. Other events for actions, buttons, and hotspots allow you to add programming to other events. After the object is loaded, the initialize event is triggered and then the click event is triggered. Examples Compose a new document Save a form Make a calculation

Agent event
The Initialize event stores all the programming associated with the agent. Always add the programming to the Initialize event for an agent.

252 Application Development with Domino Designer

Creating an unshared form action or view action


1. Launch Designer and open the form or view. 2. Choose Create - Action. The Actions Properties box appears. 3. At the Action Info tab: Enter a name. Select whether to make the action available as a menu item in the Actions menu or as a button in the action bar, or both. Select a target. If the action is a button, select the graphic for the button. Click Notes graphic to select a button design from a set available in Notes, or click Custom. When you click Custom, you can: In the Image field, specify the path name of a graphic you have created and stored in the file system. Click the folder icon and select the name of a shared image resource that you have created and stored in the database as a Resource. Click @ and specify a formula (or set of formulas). Select the location and position for the action. 4. (Optional) At the Action Hide When tab, specify when to hide the action. 5. (Optional) At the Advanced tab, specify how Notes workflow proceeds after the user activates the action. 6. In the Info List of the Programmers pane, click Objects and select the action you just created. 7. Choose one of the following from the Run pull-down list and add the automated tasks: Simple actions Formula LotusScript JavaScript 8. Save the form or view.

Chapter 10: Automation in Applications 253

Other action procedures To copy: select the action in the Action pane and choose Edit - Copy and Edit - Paste. To delete: select the action in the Action pane and choose Edit - Clear. To change properties: select the action in the Objects list and choose Design - Action Properties. To change automation: select the action in the Objects list and edit the programming tasks in the right pane. Actions menu The Actions menu is a context-sensitive list of any actions and agents available for a particular part of an application, as well as some menu commands included with the Notes software. From an open view, Notes users see only those actions associated with the view, plus any manually run agents. From an open document, Notes users see the actions associated with the form used to create the document, plus any manually run agents. Web users dont see the Actions menu. Calling an agent You can use a form or view action to run an agent. Use the @Command([ToolsRunMacro]) or the OpenAgent URL command to call an agent.

Examples: actions
Simulate Notes menus for Web users Web users dont have access to Notes menu choices when they work in Domino databases. Therefore, you should create menu equivalents for them. Create actions with @command formulas and make them available as buttons in the action bar. Keep in mind that Domino cannot translate commands based on a selected document in a view because there is no notion of a selected document on the Web. For actions such as Create Response Document, you must add a form action to the Main Topic form for opening a Response document. To Web-enable all buttons in a database as well as certain @commands, select the database property Web access: Use JavaScript when generating pages. Without this property set, Domino recognizes only the first button in a document and treats it by default as a Submit button that closes and saves the document.

254 Application Development with Domino Designer

Be aware that Domino displays all buttons, actions, and hotspots even those that contain @commands and @functions that arent supported for Web applications. Complete these steps to create a button to open a new Main Topic in the current database: 1. Launch Designer and open the view where you want to add the button for Web users. 2. Choose Create - Action. 3. Complete the Action Properties box. At the Action Info tab: Enter the name Create Main Topic. Select Include action in button bar. Select Notes graphic and select a graphic for the button. 4. In the Info List, click Objects and click Create Main Topic. 5. In the Run pull-down list, select Formula. 6. Enter this formula:
@Command([Compose];"Main Topic")

7. Save the view. Examples of other commonly used menu items: Create a document
@Command([Compose]; "formname") @Command([Compose];"":"database"; "formname")

Open a view
@Command([OpenView]; "viewname") @Command([OpenView];"":"database"; "viewname") @Command([OpenView];"By Date")

Delete an open document


@Command([EditClear])

Close an open document or view


@Command([FileCloseWindow])

Chapter 10: Automation in Applications 255

Sending a document to reviewers You want to simplify the process of distributing proposed concert schedules to a review board. 1. In the Concert Schedule form, create a field of type Names that will specify all the reviewers. 2. In the Concert Schedule form, choose Create - Action and specify the following in the properties box: Name Enter Distribute for Review. Display Select Include action in button bar; deselect Include action in Action menu. Button Graphic Select Notes graphic and pick a graphic from the pull-down list. 3. In the Info List, click Objects and select Distribute for Review (Action). 4. In the Run pull-down list, select Simple action(s). 5. Select the Add Action and Send Document actions 6. Save the form. Approving and denying requests You want to improve a Requisition form to make it easy for managers to approve or deny requests that are mailed to them. You create two form actions: Approve Request and Deny Request. The Approve Request action uses this formula to change the documents status to Approved and routes the document to the next approver:
FIELD Status:="Approved"; @MailSend(NextApprover;"";"";"For your review";"Click Approve Request to approve this requisition or click Deny Request to return the request to " + Initiator;"Initiator":"Body";[sign]);

The Deny Request action changes the documents status to Denied and routes a notification to the initiator.
FIELD Status:="Denied"; @MailSend(Initiator;"";"";"Re: Your request";"Your request was unable to be approved. Contact " + PreviousApprover + "for more information.");

256 Application Development with Domino Designer

Action bar
The action bar is a horizontal button bar that lies below the SmartIcons bar. If there are built-in actions or you created actions to be displayed as buttons, users see the buttons when they open the view or create a document using the form. You can change the color and style of the action bar, and enable the Domino action bar applet for Web users. 1. Launch Designer and choose Design - Action Bar. The Action Bar Properties box opens. 2. At the Action Bar Info tab: Alignment - lets you choose whether to have the action bar align to the left or right. Background - lets you set the background color for all buttons on the action bar. Bottom Border - in the Width field, you can choose: None does not place a divider line under the action bar. Fit to window places a divider line under the whole action bar. Under buttons only displays a divider line that is only as long as the icon display. Set length displays a divider line that is a specific number of inches. You can also set the Color of the border and choose the Style of the border line. Web Access - select whether to use the Domino applet to provide a better action bar to display to Web users. Select Using Java Applet to enable the applet. With the applet, Web users can: Scroll across the action bar, when needed. For actions that have pull-down list selections for Notes client users, the action selections are displayed as a second row of buttons when the user clicks the main action. The second row of buttons are displayed at 75% the size of the main action buttons. Web users can view all the selections and click one to select it. Select Using HTML to disable the applet.

Chapter 10: Automation in Applications 257

3. At the Button Background tab, you can customize the following properties for all buttons on the action bar: Button Size - sets the height and width in pixels of all the buttons on the action bar and sets the margin size. Button Border - lets you control when the button border displays. You can choose to display the button border On Mouse Over, Always, or Never. Button Background - lets you either select a color for the button background or use an image for the background. To use an image, click the folder icon and select the name of a shared image resource that you have created and stored in the database as a Resource, or click @ and specify a formula (or set of formulas). Note that using an image is not supported on the Web. 4. At the Button Font tab, you can change the font, size, color, and style of the text in the buttons.

Creating and inserting shared actions


Shared actions are stored in databases as Resources. Once you create a shared action, any other view or form in the database can access it. Create a shared action 1. Open the database where you want to store the shared action. 2. Click Resources; then click Other. 3. From the list of other resources, select Actions. 4. For the first shared action, the Actions properties box appears. For subsequent shared actions, choose Create - Shared Action and the Actions properties box appears. 5. At the Action Info tab: Enter a name. Select whether to make the action available as a menu item in the Actions menu or as a button in the action bar, or both. Specify a target. If the action is a button, select the graphic for the button. Click Notes graphic to select a button design from a set available in Notes, or click Custom. When you click Custom, you can: In the Image field, specify the path name of a graphic you have created and stored in the file system.

258 Application Development with Domino Designer

Click the folder icon and select the name of a shared image resource that you have created and stored in the database as a Resource. Click @ and specify a formula (or set of formulas). Select the location and position for the action. (Optional) Click the Action Hide When tab to specify when to hide the action. Click the Advanced tab and specify how Notes workflow proceeds after the user activates the action. 6. In the Info List of the Programmers pane, click Objects and select the shared action you just created. 7. Choose one of the following from the Run pull-down list and add the automated tasks: Simple actions Formula LotusScript JavaScript 8. Save the shared action. Insert a shared action 1. Open the form or view where you want to use the shared action. 2. In the Info List, click Objects and select an action, or select an action in the Action pane. 3. Choose Create - Insert Shared Action. 4. In the Insert Shared Action dialog box, select the shared action and click Insert. The shared action is added to the view or form Objects list. The next time you use the form or view, the shared action is available. Editing shared actions To edit a shared action, launch Designer and open the database with the shared action. Click Resources, click Other, and select Actions. To change its properties, double-click the action in the list and the Action property box appears. To change its automated components, click Objects and select it from the list.

Chapter 10: Automation in Applications 259

Creating a link
1. Launch Designer and open the design element you want to add the link to (a page, view, frameset, form, folder, or navigator) or edit a document. 2. Select text or an image for the link. 3. Choose Create - Hotspot - Link Hotspot. 4. At the Hotspot Info tab of the HotSpot Resources Link Properties box: At the Type field, choose one of the following: Link Link requires that you paste in a link that youve already copied to the Clipboard. Click the Paste icon to paste in the link. The links you can paste in from the Clipboard include: View, Document, Database, or Anchor. Named Element A named element is a design element that you have already created and named. A named element can be a page, form, frameset, view, folder, or navigator. Enter a value (for example, if you already created a page named PAGE1, enter it into the Value field). Alternately, you can click one of the following icons: Formula (@) icon to use a formula that evaluates to a name. Paste icon to paste in a name which you previously copied to the Clipboard. Folder icon to open the Locate Object dialog box and select a design element from a list of elements. URL Enter the full URL specification (for example, http://www.lotus.com). You can also paste in a URL or use a formula that evaluates to a URL. Frame: Specify the frame in which you want the data to display when the user clicks the link hotspot. Select whether to show a border around the hotspot. (Optional) Click the Paragraph Hide When tab to specify when to hide the link. 5. Save the design element or document.

260 Application Development with Domino Designer

Other link procedures To change properties: click the link and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the link and choose Hotspot Remove Hotspot.

Example: links
For each concert schedule you send out, you want to provide a cross-reference for more information about the performer. Create a link in the document you create for a specific concert and specify a URL with detailed information about the performer. 1. Edit the document announcing the concert. 2. Select text for the link hotspot. 3. Choose Create - Hotspot - Link Hotspot. 4. At the Hotspot Info tab of the Hotspot Resources Link Properties box: Type: Select URL. Value: Specify the Web address; for example, specify http://www.concertseries.org/performers/luke.html 5. Save the document.

Creating a button
1. Open the design element you want to add the button to (a page, view, frameset, form, folder, or navigator) or edit a document. 2. Click where you want to add the button and choose Create - Hotspot Button. 3. At the Button Info tab of the Button properties box: Button Label: Enter a name for the button. Button Width: Specify a value, in inches, for the width. 4. (Optional) At the Paragraph Hide When tab, specify when to hide the button. 5. In the Info List, click Objects and select the button you just created. 6. Choose one of the following from the Run pull-down list to add the automated tasks: Simple actions Formula

Chapter 10: Automation in Applications 261

LotusScript JavaScript 7. Save the design element or document. Other button procedures To change properties: click the button and choose Button - Button Properties. To change automation: in the Info List, click Objects, select the button in the Objects list and edit the programming tasks in the script area. To delete: click the button and choose Edit - Clear. Call an agent: use the @Command([ToolsRunMacro]) or the OpenAgent URL.

Example: buttons
Using a button to add a database to a users workspace The Human Resources department sends new employees a mail message that welcomes them to the company and gives them orientation information. You decide to add a button to the Welcome form to make it easy for new users to find Benefits information. New employees see the button when they read their Welcome message. Double-clicking the button adds Server1s Benefits Information database to the users workspace (if it isnt already there) and opens it to the View by Category view. The button uses this formula:
@Command([FileOpenDatabase];"Server1":"BENEFITS.NSF";"View by Category")

Creating a text pop-up


1. Open the form you want to add the pop-up to or edit a document. 2. Select text or an image to associate with the text pop-up. 3. Choose Create - Hotspot - Text Pop-up. 4. At the Hotspot Pop-up Info tab of the HotSpot Pop-up Properties box: Enter the text for the pop-up. Select whether to pop up the text when the user mouses over or clicks the hot spot. Select whether to identify the hotspot with a border and whether to use the highlight color or a default green.

262 Application Development with Domino Designer

5. (Optional) At the Paragraph Hide When tab to specify when to hide the pop-up. 6. Save the form or document. Other text pop-up procedures To change properties: click the pop-up and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the pop-up and choose Hotspot - Remove Hotspot.

Example: text pop-ups


Users register for conferences using a form you designed, but they frequently specify their incorrect email address. You want to give users more information about what you need in the field. Create a text pop-up to display the information when they mouse over the field label. 1. Open the form. 2. Select the field label. 3. Choose Create - Hotspot - Text Pop-up. 4. At the Hotspot Pop-up Info tab of the HotSpot Pop-up Properties box: Enter the following text:
Specify your Notes mail address, not your internet mail address. For example, specify "Ken Jones@ABC" not "kjones@abc.com".

Select Pop-up on mouse over. Select Show border around hotspot and Use highlight color. 5. Save the form.

Creating a formula pop-up


1. Open the form you want to add the pop-up to or edit a document. 2. Select text or an image to associate with the formula pop-up. 3. Choose Create - Hotspot - Formula Pop-up. 4. At the Info tab of the Hotspot Pop-up Properties box: Select whether to pop up the formula when the user mouses over or clicks the hotspot. Select whether to identify the hotspot with a border and whether to highlight the text.
Chapter 10: Automation in Applications 263

5. (Optional) At the Paragraph Hide When tab, specify when to hide the pop-up. 6. In the Info List, click Objects and select the hotspot you just created. 7. Enter its formula 8. Save the form or document. Other formula pop-up procedures To change properties: click the hotspot and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the hotspot and choose Hotspot - Remove Hotspot. To change the formula: click the Hotspot entry in the Objects list and edit the formula in the script area. Other considerations: Use formulas that display information, such as @Time. Do not use formulas that take action, such as @OpenView.

Example: formula pop-ups


1. Open the form you want to add the pop-up to. 2. Select text. 3. Choose Create - Hotspot - Formula Pop-up. 4. At the Info tab of the Hotspot Pop-up Properties box: Specify the frame in which you want the data to display when the user clicks the link hotspot. Select Show border around hotspot. 5. In the Objects list, click the hotspot and enter the following formula:
@Time(@Now)

6. Save the form.

264 Application Development with Domino Designer

Creating an action hotspot


1. Open the form you want to add the action hotspot to or edit a document. 2. Select text or an image to associate with the action hotspot. 3. Choose Create - Hotspot - Action Hotspot. 4. At the Hotspot Info tab of the Action HotSpot Properties box: Specify the frame in which you want the data to display when the user clicks the link hotspot. 5. (Optional) At the Hide When tab, specify when to hide the hotspot. 6. In the Info List, click Objects and select the action you just created. 7. Choose one of the following from the Run pull-down list to add the automated tasks: Simple actions Formula LotusScript JavaScript 8. Save the form or document. Other action hot-spot procedures To change properties: click the hotspot and choose Hotspot - Hotspot Properties. To delete, but keep the associated text: click the hotspot and choose Hotspot - Remove Hotspot. To change automation: click the Hotspot entry in the Objects list and edit the programming in the Script area. To call an agent: use the @Command([ToolsRunMacro]) or the OpenAgent URL command.

Chapter 10: Automation in Applications 265

Creating a program for an event


1. Open the design element to which you want to add automation. 2. In the Info List, click Objects and select the event. 3. In the Run pull-down list, the programming you can use for automating the event depends on the event. Choose one of the following: Simple actions Formula LotusScript JavaScript 4. Save the event.

Examples: Creating an event script or formula


Displaying a message when users close a document The following QueryClose event script for a form displays a message when users close a document theyve edited:
Sub QueryClose(Source As Notesuidocument,ContinueAsVariant Dim workspace As New NotesUIWorkspace Dim doc as NotesUIDocument Set doc = workspace.CurrentDocument If doc.EditMode Then Messagebox("Call Pat at x-314 if you have any questions.") End If End Sub

Filling in fields automatically The following script for a field Entering event fills in the FullName field by concatenating the FirstName field, a space, and the LastName field:
Sub Entering(Source As Field) Dim workspace As New NotesUIWorkspace Set doc = workspace.CurrentDocument firstName = doc.FieldGetText("FirstName") lastName = doc.FieldGetText("LastName") fullName = firstName & " " & lastName Call doc.FieldSetText("FullName", fullName) End Sub

266 Application Development with Domino Designer

Requiring a field to be filled in The following script for a field Exiting event requires users to fill in a LastName field after they fill in the FirstName field:
Sub Exiting Dim W As New NotesUIWorkspace Dim UIDoc As NotesUIDocument Set UIDoc = W.CurrentDocument If (UIDoc.FieldGetText ("LastName") <> "") Then UIDoc.GotoField "FirstName" Else UIDoc.GotoField "LastName" Messagebox "You must enter the person's last name.", 0, "ERROR" End If End Sub

Building an agent
1. Select the database where you want to create the agent. 2. Choose Create - Agent. 3. In the Name field, enter a name for the agent. 4. (Optional) If the agent searches for text in documents, click Options and specify what to search for. 5. Select Shared Agent if this agent will be used by other users. Once you save the agent, you cannot change this setting. If you dont select Shared Agent, the agent will be a personal agent that only you can run. 6. Select how, when, and where to run the agent: Select how to run the agent from the When should this agent run? list. For the On Schedule More Than Once a Day, On Schedule Hourly, On Schedule Daily, On Schedule Weekly, On Schedule Monthly, and If Documents Have Been Created or Modified options, click Schedule to set up when to run the agent. These options are not supported on the Web. For any scheduled agent, select where to run the agent from the Run on pull-down list. Specifying servers is particularly important when agents run on multiple servers and they are changing documents in databases that are replicated.

Chapter 10: Automation in Applications 267

7. Select the documents in the database the agent will process from the Which document(s) should it act on? list. These options are not supported on the Web: All unread documents in view All documents in view Selected documents Pasted documents 8. (Optional) To further specify the choice of documents, click Add Search. 9. From the Run pull-down list, choose one of the following to define the agents automated components: Simple actions Formula LotusScript Java Imported Java 10. Press ESC to save the agent. Other agent procedures Copy: choose View - Agents, select the agent and choose Edit - Copy. Delete: choose View - Agents, select the agent, and choose Edit - Clear. Select multiple agents: choose View - Agents, click the first agent, CTRL+click the next agent, and so on. Enable/Disable: If you have Designer access or above, you can disable scheduled agents to prevent servers from running them. This is useful for debugging a problem with an agent. Designers can still run disabled agents by choosing View Agents, selecting an agent, and choosing Actions - Run. After you re-enable them, scheduled agents resume their schedule. To disable individual agents: 1. Select the database and choose View - Agents. 2. Select the enabled agent and choose Actions - Disable. The checkmark disappears next to the agent name.

268 Application Development with Domino Designer

To disable all automated agents in a database: 3. Select the database and choose File - Database - Properties. 4. Click Disable background agents for this database. To enable a disabled agent, click the agent and choose Actions - Enable.

Options for running agents


You can set up an agent to run manually, based on a database activity, or on a schedule. When you schedule an agent for more than once a day, hourly, daily, weekly, or monthly, keep these points in mind: You can also specify which servers the agents run on. When agents run on multiple servers and they are changing documents in databases that are replicated, you should specify the servers they run on to prevent replication conflicts. Then, set up the databases replication schedules so they dont interfere with the agents scheduled runs. Agents are scheduled according to the interval you set up, not the exact time of day. For example, if you schedule an agent to run hourly, it runs about one hour after the last time it ran.
Run option Manually from Actions Menu Manually from Agent List When to use For user-activated agents or for WebQuerySave or WebQueryOpen agents. Not supported on the Web. For agents that are called by other agents and for agents that are still being developed. Not supported on the Web. Before New Mail Arrives For processing mail before it is listed in the mail databases; for example, to move incoming mail to a folder. With this option, the agent runs before the message is listed in the database. Therefore, do not use the Mark Documents Read simple action because documents will always be marked unread when they are listed in the database. continued

Chapter 10: Automation in Applications 269

Run option After New Mail Arrives

When to use For processing incoming mail: to respond to it, forward it, or file it. Interactive functions and functions that impede the progress of the mail router are ignored when documents are mailed into the database. For example: @DbColumn @DbCommand @DbLookup @MailSend @Prompt @Command @PostedCommand

If Documents Have Been Created or Modified If Documents Have Been Pasted

For workflow tasks where a task is performed based on new or changed documents. For documents that are pasted into the database routinely and they need to be modified as they are being pasted. Paste-activated agents cannot use @Command or @PostedCommand.

On Schedule More Than Once a Day Optionally, set up which server to run on.

For high-priority databases, such as those critical to a business process and for databases that replicate several times a day, such as workflow applications that route documents for approval. Be aware that if you schedule very frequent runs (for example, every 5 minutes), the servers performance could be affected. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web.

On Schedule Hourly Optionally, set up which server to run on.

For high-priority databases as described for On Schedule More Than Once a Day. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web. continued

270 Application Development with Domino Designer

Run option On Schedule Daily Optionally, set up which server to run on.

When to use For activities that are important but that will not cause a delay if they are only generated once a day. Examples include mailing newswire articles or generating low-priority assignments. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web.

On Schedule Weekly Optionally, set up which server to run on.

For routine tasks. Examples include generating summary reports and sending reminders. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web. For low-priority maintenance tasks. Examples include archiving documents and distributing company newsletters. A scheduled agent that uses @DbColumn or @DbLookup formulas can only access a database stored on the same workstation or server. Not supported on the Web.

On Schedule Monthly Optionally, set up which server to run on.

On Schedule Never

For agents that you do not want to run in particular circumstances. For example, use this run option for agents that do not run on the Web or for agents that are called by other agents.

Selecting where to run a scheduled agent


When you click Schedule to schedule an agent, you can also select one of the following options for where to run it: Local in Run on list Run only on your workstation. Note When you select Local, Notes does not check security restrictions when the agent is run. Any Server in Run on list Run on any server that the agent is available on. When agents run on multiple servers and they are changing documents in databases that are replicated, the agents could cause replication conflicts. Therefore, be careful about using this setting in this circumstance. Alternatively, you can specify the servers to run on to prevent replication conflicts. Then, set up the databases replication schedules so they dont interfere with the agents scheduled runs.
Chapter 10: Automation in Applications 271

Specific server name in Run on list Run only on the single server you select from the list of available servers. Choose when agent is enabled Prompt users to select a server when the agent is enabled. This option is useful for distributing agents in ready-to-use applications.

Examples of agents to run before Web users open or save documents


To perform error checking, field validation, and other processing before Web users open or save documents, create a shared agent that runs manually. Then write a formula that uses @Command([ToolsRunMacro]) to run the agent and attach it to the WebQueryOpen or WebQuerySave form events. This simulates the LotusScript QueryOpen and QuerySave form events that arent supported on the Web.

WebQueryOpen events
A WebQueryOpen event runs the agent before Domino converts a document to HTML and sends it to the browser. Domino ignores any output produced by the agent in this context. Examples for using this agent include performing large computations that arent possible with @commands or collecting statistics about who opened documents and when they did so. Note WebQueryOpen agents run when the user opens a form or document, but do not run when the user saves a document. This means that computed fields set by a WebQueryOpen agent are not saved when the user submits a document. To make sure computed fields are saved, you can either recalculate them in the WebQuerySave agent or set the form property Generate HTML for all fields.

WebQuerySave events
A WebQuerySave event runs the agent after field input validation formulas are run and before the document is actually saved to disk or mailed. The agent can modify the document or use the document data to perform other operations. The document is automatically saved after the agent runs. Do NOT have the agent explicitly save the document (for example, by calling NotesDocument.Save) because an explicit save could cause incorrect results. A WebQuerySave agent can product output to be sent back to the user. For example in a LotusScript agent, you can use the Print command to return raw HTML. If the agent produces output, then the form should not have a $$Return field because Domino will return only the agent output and ignore the field.

272 Application Development with Domino Designer

Examples for using this agent include: Performing complex field validation. If the document does not pass validation, you can prevent Domino from saving the document by adding a SaveOptions field with a value of 0 to the form. Simulating CGI programs that run on user-supplied data by programming a WebQuerySave event and adding a SaveOptions field with a value of 0 to the form. When the agent runs, you can collect field values from the filled-out form without generating a new Notes document. Collecting statistics based on data submitted by browsers, such as CGI variables, by writing a program that uses CGI variables and attaching it to a WebQuerySave event.

Setting up agent security


Users who create and run agents in Notes databases stored locally on their workstations can create and run any type of agent without any restrictions. The restrictions described in this section do not apply. For agents created and run in Notes databases stored on servers or run from the Web, you can set up several levels of security controls to prevent unauthorized operations.

Who can create agents


To control who can create agents that run on servers, use database ACLs: To create personal agents, users need Reader access or higher and have Create personal agents enabled. To create shared agents using simple actions and formulas, users need Designer access or higher. To create shared agents using LotusScript or Java agents, users need Designer access or higher and have Create LotusScript/Java agents enabled. Web users cannot create agents.

Chapter 10: Automation in Applications 273

Who can run agents


To control who can run agents on servers, use the Server document In the Address Book and database ACLs. Personal agents To control who can run personal agents, open the Server document in the Address Book and click the Security tab. In the Agent Restrictions section: If everyone who can access the server can run personal agents, leave Run personal agents blank. If only specific users can run personal agents, specify their names in Run personal agents. Web users cannot run personal agents. Shared agents To control who can run shared agents, use the database ACL. Users with Reader access or higher can run shared agents. If users are allowed to run shared agents, assign them Reader access or higher. If users are not allowed to run shared agents, do not list them in the ACL or assign them Depositer access. LotusScript/Java agents LotusScript and Java include operations that have full access to the servers system and can manipulate system time, file I/O, and operating system commands. Users or groups with unrestricted access can run an agent that includes any of these operations in the LotusScript and Java components. Users or groups with restricted access can include most operations. The only restricted commands are those that allow access to the servers system. If no one is allowed to run any type of LotusScript or Java agent, leave both Run restricted LotusScript/Java agents and Run unrestricted LotusScript/Java agents blank. If users are allowed to use most LotusScript and Java commands, then those users have restricted rights. Specify their user names in Run restricted LotusScript/Java agents. If users are allowed to run any LotusScript and Java agent, then those users have unrestricted rights. Specify their user names in Run unrestricted LotusScript/Java agents. Caution Unrestricted Java and LotusScript agents can potentially violate security. Only a limited number of trusted users should have unrestricted rights.

274 Application Development with Domino Designer

Where can agents run


To control whether agents are allowed to run on servers, use the Server document in the Address Book. Click the Security tab. In the Server Access section: If everyone running an agent that accesses the server is allowed to access the server, leave Access server blank. If you dont want users accessing the server either directly or through agents, specify the user names in Access server. Then, if a user who is not specified attempts to run an agent that accesses the server, the agent is not run. You can also specify user names in Not access server.

What operations can agents run


To control which documents agents can process, Domino checks the ACL of the database where the documents are stored, as follows: For agents that use simple actions, LotusScript, and Java, Domino checks the users ACL For agents that use formulas, Domino checks the replica ID of the database in which the agents were created. Therefore, to ensure that agents using formulas to access documents in other databases, you must list the database replica ID in each database the agent will access. To control whether agents are allowed to create databases, use the Server document in the Address Book. Click the Security tab. In the Server Access Section: If everyone is allowed to create databases, leave Create new databases blank. Then, anyone running an agent that creates new database can do so on the server. If you dont want users creating databases, specify the user names of people allowed to create databases in Create new databases. Then, if a user who is not specified runs an agent that creates a database, an error is reported and the database is not created.

When restrictions are checked


Domino checks the security restrictions differently depending on where the agent is running: If the agent is running locally or on the server If the agent is running in the foreground or background If the agent is started from the Web or the Notes client

Chapter 10: Automation in Applications 275

Local or server An agent runs locally when: It runs on a database stored on a workstation. It runs on a database stored on a local server. You specified Local in the Run on list for a scheduled agent. User starts it from the Actions menu, agent list, or the When documents Have Been Pasted trigger. When an agent runs locally, Domino does not check security restrictions, unless you have set the Enforce Local ACL option. An agent runs on the server when it is running in a database stored on a server and it is started by one of the following: Before new mail arrives After new mail arrives If documents have been created or updated On schedule more than once a day On schedule daily On schedule weekly On schedule monthly If the agent is running on a server, Domino checks all security restrictions. Foreground or background An agent runs in the foreground when a user starts it from the Actions menu or selects it from the Agents list. When running in the foreground, Domino does not check security restrictions. An agent runs in the background when it is scheduled or it is triggered by an event (for example, when documents are modified). When running in the background, Domino checks security restrictions. From the Notes client or the Web When a user runs an agent from the Notes client, the agent runs with the rights of the agent creator. Complete these steps to find out who the creator is: 1. Select the agent in the agent list and choose Agent - Agent Properties. 2. Click the Fields tab. 3. Select the $UpdatedBy field and check the user name in the right pane. When a Web user runs an agent, the agent runs using the rights of the agents creator and Domino checks the creators rights to access the database. However, you can set up the agent so that Domino checks the
276 Application Development with Domino Designer

invokers rights to access the database instead of the creators rights. Checking the invokers rights can provide more security. Complete these steps to specify that Domino verify the invokers access to the database: 4. Select the agent in the agent list and choose Agent - Agent Properties. 5. Click the Design tab 6. Select Run Agent as Web user. After selecting Run Agent as Web user, Domino prompts a Web user for their name and password when they attempt to run the agent. Domino uses the login information to check for the invokers rights in the database ACL.

Security controls for agents that are called by agents


When agents call other agents, Domino checks the security restrictions for each agent. However, when the creators of agents are different, Domino checks security as follows: If the first agent uses simple actions or formulas Domino checks all agents that are called against the rights of the creator of the first agent. If the first agent uses LotusScript or Java Domino checks each agent that is called against the rights of the creator of each agent.

Troubleshooting agents
You can experience problems running agents at several points during agent development, deployment, and implementation. There are several tools to help diagnose the problems in each stage. Simulate an agent run: for all types of agents Before running an agent on a live database, test it by simulating a run. The test also diagnoses whether the agent will run by checking security and schedule settings. Agent Log: for all types of agents The Agent Log displays information about when the agent last ran and whether it ran successfully. Notes server console: for all types of agents There are 3 server console commands available to display information about agent scheduling, status of agent queues and control parameters, and status of agent debugging settings that are in effect.
Chapter 10: Automation in Applications 277

Agent Manager debug information: for all types of agents You can specify that the Agent Manager record debug information about any combination of the following: control parameters, events, loading reports, memory warnings, performance statistics, execution reports, and scheduling. LotusScript debugger: for agents built with LotusScript that run in the foreground Choose File - Tools - Debug LotusScript and run the agent. The LotusScript debugger appears and you can run any debugging command in the agent as you would for any LotusScript program. NotesLog classes: for agents built with LotusScript or Java that run in the background The NotesLog class is added to your agent code and can capture information you want to track. The NotesLog class records the information in the Agent Log.

Simulating the running of an agent


You can simulate a run in two ways: For agents that do not call other agents and use only simple actions or formulas, use the Test menu item. For agents that use LotusScript, use the LotusScript debugger. For more complicated agents, create a test copy of the database. Use the Test menu item 1. Select the agent and choose Actions - Test. 2. Read the Agent Log and check for: How many documents would be processed What action would be taken if the agent were actually run 3. If necessary, make corrections and re-run the test. LotusScript agents 1. Choose File - Tools - Debug LotusScript. 2. Run the agent and the LotusScript debugger appears. You can then single step through the agent. Create a test database For agents that have multiple steps or complex tasks, split the process into several smaller tasks and create an agent for each. Test and fix each smaller agent first. When everything is working correctly, combine the agents into one. Then test the agent again.

278 Application Development with Domino Designer

1. Choose File - Database - New Copy to make a test copy of the database, with documents. For all agents except those that act on mailed documents, the test copy can be local. If the agent works on mailed documents, the test database must be on a server, and a Mail-in Database document must exist in the Address Book. 2. Create test documents: If the agent works on mailed documents, mail a few documents to the test database. If the agent works on pasted documents, paste a few documents into the test database. 3. Run the agent. 4. Use the other debugging tools to catch errors and make corrections. 5. Re-run the agent until it is working correctly. 6. Copy the tested agent to the live database.

Agent Log
Every time an agent runs, it writes a report with the following information: When it ran The number of documents it processed The actions it took on the documents Each new run of the agent writes over the previous log report. Domino stores the Agent Log with the database. To view the most recent Agent Log: 1. Select the database and choose View - Agents. 2. Select the agent whose log you want to check and choose Agent - Log. 3. Review the information in the Log. If you are running agents built with LotusScript or Java and the agents run in the background, you can add the NotesLog class to your agent code to record run-time information in the Agent Log.

Chapter 10: Automation in Applications 279

Notes server console commands


These server console commands support agent debugging:
tell amgr schedule

Use this command to see if the agent is scheduled to run. If it doesnt appear in the list when it should, then you know to check its schedule. This command does not list agents that are manually run from the Actions menu or Agents list.
tell amgr status

Use this command to see where your agent is running (that is, in which queue) and what parameters are in effect.
tell amgr debug

Use this command to display and change the debugger settings. These settings apply to the Agent Manager debugger that you enable in the NOTES.INI file. Tell amgr schedule Tell amgr schedule lists each agent that is scheduled to run on the current day. It lists only agents that run in the background. Check the list for the following information to make sure the agent is scheduled correctly.
Display First column: ESV Description The Agent Manager queue that the agent current is in. E: Eligible to run S: Scheduled to run V: Waiting to run What to check for If the agent is scheduled, make sure it is listed with an E or S. If it is listed, check that the correct time is listed. If the agent is not listed, check the When should this agent run setting. If the agent runs when new mail arrives or a document is created or updated, it should be listed with a V. If it isnt listed, check the When should this agent run setting. Second column: The event that activates the agent. If the agent has an incorrect SMU event or isnt listed when its S: Daily, weekly, monthly, or supposed to be, it means that more than once a day schedule you selected an incorrect M: New mail has arrived When should this agent run U: One or more documents have setting. been created or updated continued

280 Application Development with Domino Designer

Display Time of day

Description If the agent is scheduled to run daily, weekly, monthly or more than once a day, the time of day the agent will run is listed. If the agent is scheduled to run daily, weekly, monthly, or more than once a day and the time it is supposed to run hasnt gone by, then Today is listed. The agent name that is scheduled to run.

What to check for Check and make sure the agent is listed.

Today

Check and make sure the agent is listed.

Agent Name

Database Name The name of the database that the agent works in.

Make sure the agent is working in the correct database.

Tell amgr status Tell amgr status lists the number of agents in queues and other run-time statistics. Even though agent names are not listed, you can check the queue information to determine if the queues are processing the number of agents you would expect. You can also check the run-time statistics to how the Agent Manager is set up. For example, Agent Manager status information includes: The number of agents in queues waiting for events, such as New Mail and Document Update The number of agents in queues waiting for a scheduled time to elapse, such as the Scheduled Task queue The time period, such as Daytime or Weekend The maximum amount of time that a LotusScript/Java agent is allowed to run Tell amgr debug Tell amgr debug lists the Agent Manager debugger settings you specified with the Debug_AMgr statement in NOTES.INI. Use this command to make sure the debugger settings are correct and to change them using the same options that are available for the Debug_AMgr statement, except *. For example, to add options for the Agent Manager that you have already set up to display agent debugging information (-e option):
tell amgr debug -e, -l, -m, -p

Chapter 10: Automation in Applications 281

Agent Manager debugging information


You can specify that the Agent Manager record debugging information in these ways: Specify Debug_AMgr in NOTES.INI Use this statement to provide debugging information about agent loading, scheduling, and performance. When you specify Debug_AMgr, you can use the tell amgr_debug command at the Notes console to change the settings. Note If you specify that the Agent Manager display all possible debugging information, agent performance can be significantly affected. Specify Log_AgentManager in NOTES.INI Use this statement to provide a subset of debugging information of the information recorded with Debug_AMgr. Log_AgentManager does not affect agent performance as much as Debug_AMgr could. If you specify both statements, the Debug_AMgr settings take precedence. Debug_AMgr To specify that the Agent Manager record debug information, edit notes.ini and add the following statement:
Debug_AMgr=option

where option can be one or more of the following: c list agent control parameters e list Agent Manager event information l (lowercase L) list agent loading information m list agent memory warnings p list agent performance statistics r list agent run-time reports s list Agent Manager scheduling information v (verbose) list more information about agent loading, scheduling, and queues * list all of the information for all options After you specify Debug_AMgr in NOTES.INI and you run an agent on a server, check the Notes console and Notes Log for the debugging information. Optionally, you can redirect the debug information to be

282 Application Development with Domino Designer

recorded in a separate file on the server. When you redirect the debugging information to a separate file, performance can be affected. To redirect information, edit notes.ini and add the following statement:
DEBUG_OUTFILE=<file-name>

If you run an agent on a database stored on your local workstation, you must redirect the output because the Notes console is only on the server. Log_AgentManager To specify that the Agent Manager record less debugging information than with Debug_AMgr, edit NOTES.INI and add the following statement:
Log_AgentManager=option

where option can be one of the following (but not more than one): 0 do not list debugging information 1 list partial and complete information about successful agent runs 2 list complete information about successful agent runs

NotesLog Class
Use the NotesLog class in LotusScript and in Java agents that run in the background. Add the NotesLog class to your agent code to record run-time information. It is particularly helpful for capturing variable values, error handling, and verifying code logic. By default, the NotesLog class records information to the Agent Log. When you set up items you want recorded, make sure you dont exceed the Agent Log limit. To use NotesLog, follow this LotusScript example that tracks the documents an agent is processing by capturing the documents Subject. The information is recorded in the Agent Log.
Dim agentLog As new NotesLog("Agent log") Call agentLog.OpenAgentLog Set s=New NotesSession Set db = s.CurrentDatabase Set collection = db.UnprocessedDocuments Set note = collection.GetFirstDocument count = collection.Count Do While (count >0) Subject = note.Subject Call agentLog.LogAction("Processing:"+Subject(0)) Set note = collection.GetNextDocument(note) count = count-1 Loop Call agentLog.Close

Chapter 10: Automation in Applications 283

Agent Log limit The Agent Log can hold only 64KB of information. When the information written to it exceeds this limit, the following message is displayed and the agent stops running: Error executing agent <agent-name> in <database-name>. Memory allocation request exceeded 65,000 bytes. Make sure that the information you want recorded to the Agent Log does not exceed this limit. If it does, rework the NotesLog class code to record less information per run.

AgentRunner
AgentRunner is a Java application program for debugging Domino agents in a Java IDE. There are two versions of AgentRunner for different package classes: lotus.domino.AgentRunner for lotus.domino (Notes/Domino, Release 5.0) lotus.notes.AgentRunner for lotus.notes (Notes/Domino Release 4.6.x) Also included is a set of debug classes that access Notes context information while running in a Java IDE. To use AgentRunner: 1. Create agent code to extend DebugAgentBase. 2. Run the agent to generate an AgentContext document in the AGENTRUNNER.NSF. 3. Run AgentRunner that runs your agent code outside Notes. The AgentRunner code accesses the AgentContext document to make the program behave as though it were running as an agent. This allows you to build and run without having to switch between the IDE and Notes, and to use IDE run-time tools such as the debugger. Create a project for your agent In Java IDE: 1. Add the fully-qualified file specification for NOTES.JAR (for example, for JDK or Cafe) to your Java IDEs CLASSPATH or Import (for example, for VisualAge) the JAR file to your project. 2. Create an agent (see the Domino Designer Programming Guide) that extends DebugAgentBase, instead of AgentBase. Note To select the correct version of DebugAgentBase:

284 Application Development with Domino Designer

For Notes, Release 4.6-style agents use the import lotus.notes.*; format. (Recommended) For Notes, Release 5 use import lotus.domino.*; 3. Build the project as an application. It does not matter if the agent has a main() method, but if your IDE requires one, add a dummy one. Notes will not use it. 4. If required (for example, for VisualAge), export the .CLASS files. Generate an AgentContext document In Notes: 1. Build a Java agent in a Notes database and import the .CLASS files from your project. Ensure that the base class is the class that extends DebugAgentBase. 2. Run the agent to generate an AgentContext document in AGENTRUNNER.NSF. Note When the agent runs in Notes, a call to getSession() from an agent class that extends DebugAgentBase returns NULL after generating an AgentContext document. Therefore, any use of the returned session results in a thrown exception. Because the purpose of running the agent is only to generate the context document (and not to run any of the agent code), you can ignore the exception. 3. Open AGENTRUNNER.NSF and examine the most recent AgentContext document. Note the name of the server, the file path of the database, and the name of the agent. Local is the name of the server for a local database. 4. Edit the AgentContext document and change the Agent Runs On and Search Criteria fields to generate the UnprocessedDocuments collection that you would like to use for debugging. You must supply this information because it cannot be determined from running the agent. Note the Agent Runs On and Search Criteria that you specified in the agent that you ran to generate this document will produce the Selected document list. 5. Save and close the document. You can generate another AgentContext document later if you want to change the run-time environment. You can edit fields other than Agent Runs On and Search Criteria to change the run-time environment, but it is not recommended.

Chapter 10: Automation in Applications 285

Run AgentRunner to debug your agent In Java IDE: 1. Specify <Agent> [<Database> [<Server>]] arguments, as displayed in the AgentContexts view of AGENTRUNNER.NSF, to the AgentRunner program to select the AgentContext document that you want to use for debugging your agent code. If running from a command line, enter:
java lotus.domino.AgentRunner <Agent> [<Database> [<Server>]]

To run an agent that uses the lotus.notes package (from Notes, Release 4.6.x) from a command line, enter:
java lotus.notes.AgentRunner <Agent> [<Database> [<Server>]]

2. Set a breakpoint on the first executable line of code in the NotesMain() method of your agent. 3. Build the project. 4. Run or debug the project. If you are debugging and no breakpoints are set, you should step into NotesMain() to access your code. 5. In certain IDEs (like Symantecs Visual Cafe), you cant specify that a projects main() entrypoint be in a class in the JAR or ZIP file. For these IDEs, you must create a dummy main application with the only purpose to call the main() method in AgentRunner. For example:
import lotus.domino.*; public class Main { public static void main (String[] args) { try { AgentRunner.main(args); } catch (Exception e) { e.printStackTrace(); } } }

286 Application Development with Domino Designer

Simple actions for automation components


Use simple actions with shared and unshared actions, buttons, action hotspots, and agents. Web applications do not support simple actions. Copy to Database Copies the selected document to the database you specify. You can copy and paste selected documents in the same database or another database on the same server where the agent is running (that is, you cannot copy documents to a database on a server other than the agents own). They are marked as read in the target database. To specify: 1. Click Choose Database. 2. Select the server and target database. Copy to Folder Copies the selected document to the folder you specify. You must create new folders before you can select them. Copying a document from one folder to another does not remove the document from the source folder. A duplicate of the document is not created; instead the document is displayed in a new place. Delete from Database Deletes the selected documents from the database. If there are replicas of this database on other servers, documents deleted in this database are also deleted in the replicas unless Do not send deletions made in this replica to other replicas is selected in your database replication settings (choose File Replication - Settings and click Send to see what the settings are). Mark Document Read Marks selected documents as read. Use this action to mark an unread document as read without opening it or for reverting a document that was modified back to its read status because it doesnt actually need to be read again for example, if it has been modified by an agent. Combine this action with one that changes field values. Then when users change the values in a document, they can mark it read at the same time. Do not use this option with an agent that is processing documents with Before New Mail Arrives.

Chapter 10: Automation in Applications 287

Mark Document Unread Marks selected documents as unread. Use this action for flagging a document that users want to read again. Modify Field Replaces or appends a single field value with a new text value you specify. This action replaces only text values for documents in Edit mode. To replace a value with something other than text, use an @function formula or LotusScript program. This action can modify the value of a hidden field, if you can specify the fields name. The Append Value option does not work for rich text, number, or time fields or for fields that are not available within documents already saved in the database. Also, Append Value is not available if a database does not contain any documents (for example, a database template). To include Append Value in databases without documents: 1. Create a placeholder document containing the field. 2. Create the agent using the field from the placeholder document. 3. Delete the document. Optionally, you can use a formula instead of a simple action. To specify a value: 4. Select the field to be modified from the Field pull-down list. 5. In the Value text box, enter the new value. 6. Select Replace value or Append value. Modify Fields by Form Replaces several field values on a form with new text values you specify. This action replaces only text values. To replace a value with something other than text, use an @function formula or LotusScript program. This action marks processed documents as read. To specify: 1. Select the form. 2. Enter the new value in the fields.

288 Application Development with Domino Designer

Move to Folder Moves the highlighted document in a view or folder to a different folder. This action removes the document from the source folder and adds it to the specified folder. The document is not deleted from the database. Remove from Folder Removes selected documents from a folder you specify but does not delete the documents from the database. If a document is included in several folders, this action removes the document from the specified folder, but does not remove the document from other folders. If a document is included in only one folder, this action removes the document from the folder and changes its category to Uncategorized. Reply to Sender Sends a reply to a mail memo automatically. Replies are not sent to a mail memo that was generated by an agent. The Body field accepts only plain text. It does not accept styled text, graphics, or attachments To specify: 1. Select Reply to sender only or Reply to all. 2. In the Body field, enter the reply text. 3. (Optional) Click Include copy of document to append the original message to your reply. 4. Select Reply only once per person if a person is included in multiple mailing groups. Run Agent Allows you to chain agents together with other agents or combine LotusScript programs, @function formulas, and Java in one agent. The agent to be run must already exist in the database. The documents that additional agents process are determined by the first agent. All subsequent agents use the same documents, regardless of their own settings. The first agent completes its search and actions first and then passes that information to the second agent. For example, Agent A searches for all documents with the word green, replaces green with yellow, and then runs Agent B. Agent B launches its own search queries and actions only on the documents that Agent A processed.

Chapter 10: Automation in Applications 289

Send Document Mails the current document to the recipients designated in the documents SendTo field. This action works like the @MailSend function. To predict the recipient, the document must have a SendTo field. If it doesnt, Notes uses the contents of the internal $UpdatedBy field as the recipient. If the document also contains the CopyTo or BlindCopyTo fields, it is routed to those recipients at the same time. If the document contains the DeliveryPriority, DeliveryReport, or ReturnReceipt fields, they control the delivery priority, generation of a delivery report, and generation of a return receipt. If the document doesnt contain these fields, they default to normal priority, no delivery report, and no return receipt, respectively. Send Mail Message Mails the selected document as a whole document or as a link. The Body field accepts only plain text. It does not accept styled text, graphics, or attachments. To specify: 1. Specify recipients in the To field. 2. (Optional) Click More to specify more addresses using text or formulas for the To:, cc:, bcc:, and Subject: fields. 3. Enter a subject. 4. In the Body field, enter the message text. 5. (Optional) Click Include copy of document to append the document to the message. 6. Select Reply only once per person if a person is included in multiple mailing groups. Send Newsletter Summary Searches a database for documents matching conditions you specify, then sends a summary document with links to the individual documents. The summary information includes items such as a one-line description of the Date, Author, and Title columns. The Gather at least option does not apply to sending a document summary from a view or folder with an action because the action can act on only the highlighted document, and Gather at least acts on multiple documents.

290 Application Development with Domino Designer

To specify: 1. Specify recipients in the To field. 2. (Optional) Click More to specify more addresses using text or formulas for the To:, cc:, bcc:, and Subject: fields. 3. Enter a subject. 4. In the Body field, enter the message text. 5. Select Include summary for each document using view to send a text summary of each document. Deselect it to send only document links. 6. Choose a view. @Function Formula Adds a customized @function formula.

LotusScript for automation components


Use LotusScript for shared and unshared actions, buttons, action hotspots, events, and agents. LotusScript can be used to access data in Notes databases and in external applications. For example: you can use LotusScript to change a value in one document based on values in other documents or modify database ACL lists. Refer to the Programming Guide and the LotusScript Language Guide for more information about LotusScript. Working with HTML You can use the LotusScript Print statement with HTML as follows: To display HTML information For example, add this line to display the message Thank you for your submission:
Print "<H1>Thank you for your submission</H1>"

To provide instructions to a browser For example, add this line to direct a browser to the Domino Web site:
Print "[http://domino.lotus.com]"

Chapter 10: Automation in Applications 291

Restrictions for using the Print statement include: It must be attached to a user-run automated component, such as an action, a button, a manually-run agent, or a WebQuerySave event that uses @Command([ToolsRunMacro]). If it is attached to a manually-run agent, it must also be a shared agent. It cannot be attached to a WebQueryOpen event.

Restricted LotusScript and Java agent operations


Restricted backend class and method
Task Using a disk-based log file Using Environment variables LotusScript NotesLog OpenFileLog(path) NotesSession GetEnvironmentString() NotesSession SetEnvironmentVar() NotesSession GetEnvironmentValue (SystemVariable,true) Encrypting or signing Embedded Object manipulation NotesDocument Sign() NotesDocument Encrypt() NotesRichTextItem EmbedObject() NotesEmbeddedObject ExtractFile(path) Java Log openFileLog(path) Session getEnvironmentString() Session SetEnvironmentVar() Session GetEnvironmentValue(Syste mVariable,true) Document sign() Document encrypt() RichTextItem embedObject() EmbeddedObject extractFile(path)

292 Application Development with Domino Designer

Restricted programming language operation


Task File I/O LotusScript Open statement Chdir statement Chdrive statement close statement curdir statement dir statement eof statement fileattr statement filedatetime statement filelen statement freefile statement get statement getfileattr statement input statement input # statement inputb statement line input # statement loc statement lock statement lof statement mkdir statement reset statement rmdir statement seek statement setfileattr statement unlock statement width statement write statement N/A Date and Date$ statements Time and Time$ statements Calling a C routine Executing another application External C calls Declare statement ActivateApp statement Shell statement Not allowed Not allowed Java No file I/O operations allowed

Network I/O Setting system date/time

No network I/O operations allowed Not allowed

Note Your ability to use the LotusScript NotesDatabase Create and CreateReplica methods is controlled by the "Create New Databases" and "Create Replica Databases" fields in the Server document in the Domino Directory.

Chapter 10: Automation in Applications 293

Formulas for automation components


Use formulas for shared and unshared actions, buttons, formula pop-ups, hotspots, events, and agents. Using @Command formulas with actions and hotspots When an action or hotspot uses an @Command formula, the formula works only when it runs in the appropriate context. Keep the following in mind: A hotspot or action can process a field or an entire document, but not a selected area. When you point to the button to activate it, you lose the previous selection that is, the previous highlight disappears, and only the button is highlighted. To work around this, use @Command with parameters such as EditLeft or EditRight which move the focus within a document. Then when the user activates the hotspot or action, Notes uses the formula to determine what is affected. Formulas designed to edit a field dont work when the document is in read mode. To work around this, use @Command([EditDocument]) to put a document in edit mode. About security features that affect automation formulas Automated components with formulas run by users work only if users activate them in the correct context and have enough privileges to perform the automated task. For example, if a formula in a hotspot uses @SetField to change a field value, the hotspot doesnt work when the user activating it has only Reader access or the document is in read mode. An automated component with formulas cannot usually complete unauthorized tasks on a database stored on a server because most users do not have privileges that allow them to run such tasks. However, in a local database where you have Manager privileges by default, an automated component with a formula could potentially change documents. If you are unfamiliar with the formulas associated with an automated component, review them first.

294 Application Development with Domino Designer

If the users notes.ini file includes this statement


NoExternalApps=1

then any formula involving the following features is disabled: @Command @PostedCommand @DbCommand, @DbColumn, @DbLookup (only if it refers to a non-Notes database) @MailSend Dynamic Data Exchange (DDE) including all @DDE functions Object Linking and Embedding (OLE) Launching attached files The user doesnt see a message, but the formula wont run.

JavaScript for automation components


Use JavaScript for shared and unshared actions, buttons, action hotspots, and events. JavaScript Version 1.3 is currently supported. JavaScript is particularly useful for providing interactive components, such as: Form and field validation Mouse effects (such as image rollover buttons and friendlier URLs) Numeric calculations Dialog box simulations When you use JavaScript, more processing can be done at the workstation instead of the server, thereby reducing network traffic and improving run-time task processing. JavaScript works with Notes objects, such as a window, document, or field. The objects that you can attach JavaScript to vary, according to the component you are working on. In the Info List, click Objects to see what is available. For example, set up a JavaScript automated task for an OnClick event in a hotspot. You can also check this table to see what JavaScript objects are available in each automated component and whether they are supported in different browsers and the Notes client.

Chapter 10: Automation in Applications 295

Table of supported JavaScript objects for automated components


This table lists the JavaScript objects that are available for automated components and which browsers support the event.
JavaScript Object Button Action Hotspot Form Action Shared Action Form View Action Shared Action View

onBlur Works in Doesnt work in

Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer Notes browser, Notes client, Netscape Notes client, Netscape, Internet Explorer

onClick Works in

Doesnt work in onDblClick Works in

Notes browser

Notes browser

Notes browser

Notes browser

Notes browser

Netscape, Notes Netscape, Netscape, Netscape, Netscape, Internet client, Internet Internet Internet Internet Explorer Netscape, Explorer Explorer Explorer Explorer Internet Explorer Notes Notes browser, browser Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client

Doesnt work in

onFocus Works in Doesnt work in

Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape continued

296 Application Development with Domino Designer

JavaScript Object

Button

Action Hotspot

Form Action

Shared Action Form

View Action

Shared Action View

onHelp Works in Doesnt work in

Internet Internet Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape

Internet Internet Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape

onKeyDown Works in Doesnt work in

Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape

onKeyPress Works in Doesnt work in

Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape

onKeyUp Works in Doesnt work in

Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape

onMouseDown Works in Doesnt work in

Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client continued

Chapter 10: Automation in Applications 297

JavaScript Object

Button

Action Hotspot

Form Action

Shared Action Form

View Action

Shared Action View

onMouseMove Works in Doesnt work in

Internet Netscape, Internet Internet Internet Internet Explorer Internet Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client, Netscape Notes browser, Notes client Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape Notes browser, Notes client, Netscape

onMouseOut Works in Doesnt work in

Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client

onMouseOver Works in Doesnt work in

Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client

onMouseUp Works in Doesnt work in

Netscape, Netscape, Netscape, Netscape, Netscape, Netscape, Internet Internet Internet Internet Internet Internet Explorer Explorer Explorer Explorer Explorer Explorer Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client Notes browser, Notes client

298 Application Development with Domino Designer

Importing Java programs


Agents running on Domino servers can run Java programs. Domino supports Java, Version 1.1x and later. 1. After you select Imported Java from the Run pull-down list, click Import Class Files. 2. In the Define Java Agent Files dialog box: Select Local Filing System from the Browse pull-down list. In Base Directory, enter the path for the Java files. In Base Class, enter the name of the main class. 3. Do one of the following: Click Select All to add all the Java files. Select them one-by-one and click Add/Replace File. 4. Make sure the files in the Current Agent Files List are in the same order that they should run. If not, re-order them using the Reorder Up and Reorder Down buttons.

Creating Java programs for agents


Requirements To use Java programs, write class files in advance that meet these requirements: Use Java Version 1.1.x or later. Use the Java Notes classes to access Notes Extend the lotus.notes.AgentBase class. Java Notes classes parallel the LotusScript Notes back-end classes. You can use these classes from any Java program, within Notes or outside, as long as Notes Release 4.6 or later is installed. When the agent runs, it should run code in the NotesMain() method. There must be a Base Class file, which is the starting point for the agent code. Other files can include other source (*.java) files, Class (*.class) files and Archive (*.jar) files. See the Domino Designer Programming Guide, Volume 3 for detailed information on the Java classes.

Chapter 10: Automation in Applications 299

Create the Java program 1. After you select Java from the Run pull-down list, Designer sets up: Base Class file with the name of the agent and the .java extension. A Classes list with the required NotesMain() method. Stub code for the Base Class and the NotesMain() method in the right-hand pane of the Programmers pane. 2. Complete the code in the NotesMain() method. 3. Click New Class to add classes. 4. Click Edit Project to associate Java files with the Base Class. 5. (Optional) Click Export to store the Java file independently of the agent on your computer. 6. Save the agent.

Actions and agents names


The names you give to manually-run agents appear as choices in the Actions menu. The names you give to form actions and view actions appear as choices in the Actions menu and on the action bar. The names are case-sensitive and can be any combination of characters, including letters, numbers, spaces, and punctuation.

Naming tips
Choose short names for form and view actions that you design to appear as action bar buttons. Choices on the Actions menu appear in alphabetical order. To force names to appear in a different order, number or letter them. Use consistent names across databases to enable users to recognize identical agents and actions.

Naming techniques
Alias names An alias is an internal name for an agent. Using an alias, you can change or translate the name that users see without disabling formulas that reference the original name. Aliases follow the same naming rules as regular names. Alias names dont work with form and view actions.

300 Application Development with Domino Designer

To create an alias name, add the alias name and a | (vertical bar) symbol to the left of the original name. Always keep the original name as the rightmost name.
Archive Documents | Agent1

Shortcut keys A shortcut key is an underlined letter in a choice on the Actions menu. Windows, OS/2, and UNIX users type only the shortcut letter to select the menu item. To specify a shortcut, type an underscore before the letter you want to assign as the shortcut. For example, S is the shortcut for this Save action:
_Save

Notes ignores the underline when it displays the name of an action on the action bar. Cascading names If you dont want to overwhelm users with long lists or if you have related actions or agents that should be grouped together, group them so that related menu choices appear under one main menu choice. You can create only one level of cascading names. Enter the name you want to appear on the Actions menu followed by a \ (backslash), followed by the action or agent name. For example:
Mail Tools\Add Sender to Address Book Mail Tools\Choose Letterhead

Actions that also display in the action bar show only the name after the backslash. The Calendar Profile agent in the Combined Mail (4.6) template contains a name that has a shortcut key, a cascading name, and an alias:
_Calendar Tools\Calendar Profile . . . | Calendar Profile

Chapter 10: Automation in Applications 301

Hiding automated components


When you create most automated component, you can hide them under varying conditions. Use the Hide tab of the Properties box to specify when to hide it. Hide from Notes R4.6 or later Hides a component when it is viewed from a Notes workstation. This is useful for hiding components such as action bar buttons that you provide to Web users as substitutes for Notes menu choices. Hide from Web Browsers Hides a component when it is viewed from a Web browser. This is useful for hiding components that arent relevant to Web users. Hide when opened for reading; Hide when previewed for reading Hides a component when a document is opened in read mode from the Preview pane or as an open document. These options are useful for components that are relevant only to new documents or documents in Edit mode for example, actions that modify a field. Hide when previewed for editing; Hide when opened for editing Hides a component when a document is opened in edit mode from the Preview pane or as an open document. These are useful for components that are relevant only to completed documents for example, moving documents to another database, creating response documents, or marking documents as unread. Hide when printed Hides the component when users print a document. This is useful for removing clutter from a printed document. Hide when copied to the clipboard Hides the component when users copy a document. This is useful for removing clutter from a copied document. Hide if formula is true Hides the component under certain conditions for example, based on user name or access level in the access control list. For example, the following formula hides the component from all users except Barbara Meehan:
@If(@Name([CN];@UserName) !="Barbara Meehan";@True;@False)

302 Application Development with Domino Designer

Chapter 11 Including Java Applets in Applications


This chapter describes adding Java applets to forms, documents, and pages. Although Java applets are used mostly for Web applications, you can also include them in Notes applications.

Java applets overview


You can include Java applets in the following elements of a Domino application: Form The applet is included in each document created with that form. Document The applet is available only in the document. Page The applet is available only in the page. Although Java applets are mostly used for Web applications, you can also include them in Notes applications. To include a Java applet in an application: 1. Enable Java applets on your workstation. 2. Import the applet from files on your workstation or on a file server, or link to an applet on the Web. 3. Use the Programmers pane and the Properties box to set applet parameters, attributes, and properties. Some applets will run with no modification, but most require that you set parameters or attributes before you can run them. 4. Correct problems with the Java applets. If the applet doesnt run, you may need to include additional files or set additional parameters. 5. Optionally, you can set up shared applet resources, that is, set up related files so that they can be used by several applets. For more information about Java or to find applets you can use, see the Java Web site at http://java.sun.com.

303

A Java applet usually consists of a collection of files, with one file that contains the main class, or the starting point for the applet. There can also be image files, archive files, and Java source files. You can store Java applet files as follows: When you import an applet, the files are attached as hidden files to the form, document, or page where you include the Java applet. When you link to an applet, files are stored on the Web and a URL reference to those files is stored in the form, document, or page where you include the Java applet. When you set up shared applet resources, the files are stored in the database where you include the Java applets that use those files.

Requirements and restrictions for Java applets


To create a Java applet, use the NetObjects BeanBuilderTM or another authoring tool. You cannot use Designer to create a Java applet. To include Java applets in an application, you must install Designer. Supported browsers include Internet Explorer 3.0 or 4.0 and Netscape 3.0 or 4.0. Java applets created with Notes 4.6 and 5.0 will not work with previous releases of Notes, unless the applet is stored on the Web and it has no parameters. Java applets created with Notes 4.5 will work with Notes 5.0. If you use Notes 5.0 to change the applet parameters, the applet is saved as a 5.0 applet and will no longer work in 4.5.

Enabling Java applets


Before you can add a Java applet to a Domino or Notes application, you must set up your workstation. 1. If you want to link to applets on the Web, make sure your Location document specifies a valid Web proxy. See your system administrator if you have questions about setting up a Web proxy. 2. Choose File - Preferences - User Preferences. 3. In the Basics tab, scroll down the Advanced Options list and select Enable Java applets. Note If Enable Java Applets is not listed, check with your system administrator. 4. Click OK.

304 Application Development with Domino Designer

Importing an applet
Before you import a Java applet, you must enable Java applets on your workstation and make sure all the related files are available on your workstation. 1. Launch Designer and open a page or form, or click in the rich text field of a document. 2. Choose Create - Java Applet. 3. In the Create Java Applet dialog box: Select Import an applet from the file system or use an applet resource. In Base Directory, enter the path for the applet files. In Base Class Name, enter the name of the main class. To avoid typing the path and class name, click the folder icon to browse for the main class file for the applet. Clicking the main class file inserts the class and the path in the correct fields. 4. Click Locate to see all related files for the applet. 5. Select the related applet files and click Add/Replace File. If you are inserting an applet that is packaged as a .JAR file, select the .JAR file, and click Add/Replace File to include the .JAR file. 6. Click OK twice. 7. (Optional) Set applet parameters, attributes, and properties.

Getting the main class name


One way to make sure you have the correct name for the main class (which you enter in the Create Java Applet dialog box) is to use any text editor to open the associated *.HTML file and check for this HTML tag:
<applet code=filename.class>

For example, the main class name for the following Java applet is ArcTest.class.
<applet code=ArcTest.class width=400 height=400></applet>

Selecting related files


Applet files can be of the following types: Class *.CLASS Archive *.JAR, *.ZIP, *.CAB Resource *.JPG, *.JPEG, *.GIF, *.AU Source *.JAVA
Chapter 11: Including Java Applets in Applications 305

For most applets, you must select all class and resource files. Select the source files only if you plan to send the applet to another user who wants to export them and change the applet. If you are inserting an applet that is packaged as a .JAR file, you can enter the path and the main class name as described above. Note that browsing for the .JAR file inserts the filename with a .CLASS extension in the Class Name field. In some cases, the file name and the main class name are the same; in other cases, they are different and you must edit what appears in the Class Name field to be the correct main class name. If you have more than one applet in a form, document, or page, Notes stores only one copy of common files.

Importing applets packaged as .CAB or .ZIP files


If you import an applet that is packaged as an archive file (such as either a .CAB or .ZIP file), consider the browsers the application users have: For Internet Explorer users, include the .CAB file. Note Domino does not display an embedded applet that is packaged as a .CAB file. For Netscape users, include the .ZIP and .JAR files. If users are likely to use either or both browsers, include .CAB, .JAR, and .ZIP files. Domino creates the appropriate parts of the APPLET tag for these files. Netscape ignores the CABBASE (or CABINETS) parameter and Internet Explorer ignores the ARCHIVE attribute.

Linking to an applet on the Web


Before you link to a Java applet on the Web, you must enable Java applets on your workstation. 1. Launch Designer and open a page or form, or click in the rich text field of a document. 2. Select Create - Java Applet. 3. In the Create Java Applet dialog box: Select Link to an applet on a Web server. In Base URL, enter the URL where the applet files are stored. In Base Class Name, enter the name of the main class. 4. Click OK. 5. (Optional) Set applet parameters, attributes, and properties.

306 Application Development with Domino Designer

For the URL, specify the name of the URL where the applet resides, not the document that references the applet. For example, use
http://java.sun.com:80/applets/Bubbles

instead of
http://java.sun.com:80/applets/Bubbles/index.html

Java is case-sensitive, so check the capitalization of the class file.

Setting applet parameters


Some Java applets have parameters that use default values. You do not need to specify values for these parameters. For applets that have parameters without default values, however, you must set parameter values or the applet will not run. You can manually enter parameters and values, or you can paste all of the parameters and edit associated values. To set individual applet parameters 1. Select the Java applet and, if the Programmers pane is not displayed, choose Java Applet - Java Applet Parameters. 2. Click Applet Parameters in the Info List of the Programmers pane. 3. Use any text editor and open the HTML file associated with the Java applet. If you imported the applet, check the HTML file on your file system. If you linked the applet, use a Web browser and check the HTML file on the Web. For example, on Netscape you can choose View - Page Source to see the HTML file. 4. Click Add. 5. Enter the parameter name. For example, enter bgcolor for the following HTML tag:
<param name=bgcolor value="black">

6. Enter the corresponding value in the Parameter Value window. For example, enter black for the example HTML tag in Step 5.

Chapter 11: Including Java Applets in Applications 307

To set all applet parameters 1. Use any text editor or Web browser and open the HTML file associated with the Java applet. 2. In the HTML file, select all of the parameters and copy them to the Clipboard. For example, copy all of the following text:
<param name=bgcolor value="black"> <param name=fgcolor1 value="red"> <param name=fgcolor2 value="magenta">

3. Select the Java applet and if the Programmers pane is not displayed, choose Java Applet - Java Applet Parameters. 4. Click Applet Parameters. 5. Click Paste to add the parameters and their values. Details To change a parameter value, click its name. Then change its value in the Parameter value window. The parameter value is a formula; therefore, you must enclose text values in double quotes. In addition to text strings, a parameter value can be an @function or a field name. If you are running an applet through a browser, you can add JavaScript to a form or document to interact with the applet by calling its public methods or setting/getting its public properties.

Setting applet parameters, attributes, and properties


After importing or linking an applet, you may need to set one or more of the following so that the applet runs correctly: Parameters specify values the applet needs at start-up and for correctly displaying the applet in your application. The HTML file lists parameters for the applet in <param> tags. To set parameters, use the Programmers pane and click Applet Parameters. Body attributes specify values that are specific to a browser, such as alignment values. Attributes are set at run time using a formula. Domino uses the formula to generate HTML code that is placed in the <applet> tag. To set attributes, use the Programmers pane and click HTML Body Attributes.
308 Application Development with Domino Designer

Alternate HTML are attributes usually used by browsers that do not support Java. Domino uses the Alternate HTML attributes to generate HTML code that is placed in the <applet> tag. To set Alternate HTML attributes, use the Programmers pane and click Alternate HTML. Properties specify how the applet appears in the page, form, or document where you have imported or linked it. You can also use Java applet properties to hide the applet under specific conditions. To set properties, use the Java Applet Properties box.

Setting HTML attributes


1. Select the Java applet and, if the Programmers pane is not displayed, choose Java Applet - Java Applet Parameters. 2. Click HTML Body Attributes. 3. Enter an HTML attribute in the formula window.

Setting Alternate HTML attributes


Use Alternate HTML for a browser that does not support Java. 1. Select the Java applet and if the Programmers pane is not displayed, choose Java Applet - Java Applet Parameters. 2. Click Alternate HTML. 3. Enter text or a formula. For example, enter the following text to notify users that they cannot use their browser with the Java applet:
"You're trying to run a Java applet with a browser that doesn't support Java. You can run this applet with Domino, Netscape Versions 3 and 4, or Internet Explorer Versions 3 and 4."

Use the Text to display when applet is not running property in the Java tab of the Java Applets Properties box to specify text that a browser displays when it supports Java but cannot display the Java applet.

Chapter 11: Including Java Applets in Applications 309

Setting properties
Use the Java Applet Properties box to set some applet properties (for example, height, width, and display) and application properties (for example, alignment and whether to hide the applet). 1. Select the Java applet and choose Java Applet - Java Applet Properties. 2. Edit the properties. For example, enter the following in the Text to display when applet is not running field:
This Java Applet is not currently available.

Java applet properties The properties you can set for a Java Applet include the following: Base class The name of the main class file. DocBase Provided for information only. You cannot edit it. CodeBase CodeBase is the path storing the class files, relative to the base class file. If you linked to an applet on the Web, the URL of the directory containing the applet is displayed, and you can edit the URL name. Otherwise, the field is provided for information only. Size The Height and Width fields set the height and width of the applet display area in the Domino application where the applet is running. If the applet is too large to run in the default size, you must reset these settings, using the height and width settings from the HTML file. To determine the applet size, use any text editor or Web browser to view the HTML file. Check the width and height values specified in the <applet> tag. Enter these values in the Width and Height fields. You can also specify a size for the applet as a percentage of its parent window. Text to display when applet is not running Domino displays the text you specify when it cant run the applet. Enter a simple text string, such as This applet is not working at this time. Applet uses Notes CORBA classes Select this to let Web users access the applet. If you dont select this setting and a Web user tries to run the applet, an error is generated.

310 Application Development with Domino Designer

Applet uses CORBA SSL security If you select Applet uses Notes CORBA classes, this setting becomes available. Folder tab If you import an applet, the folder tab displays all applet files. Otherwise, the page is blank. Hiding an applet under certain conditions You can hide an applet so it appears only under certain conditions in the form or page. Click Paragraph Hide When tab in the Java Applet Properties box and choose one of the following options: Hide paragraph from You can hide the applet according to how a user is accessing it: from Notes or from a Web browser. Hide paragraph when document is You can hide the applet according to how the document is being used. For example, you might hide the applet when the document is open for editing. Hide paragraph if formula is true You can customize the conditions for hiding the applet by writing a hide-when formula that specifies the criteria for hiding the applet. If you want to hide an applet based on the browser accessing it, complete these steps: 1. Create a field named HTTP_USER_AGENT in the form where you imported or linked the applet, or in the form used by the document where you imported or linked the applet. 2. For the field type, select Text and Computed for display. Optionally, you can hide the field. 3. Enter the following formula for its value:
HTTP_USER_AGENT

When a user accesses a document that uses this form, the Web server fills in the field with a string describing the browser type and version. The format of the string differs according to the browser. Some examples:
Mozilla/3.0Gold (WinNT; I) Mozilla/2.0 (compatible; MSIE 3.02; Update a; Windows 95)

Chapter 11: Including Java Applets in Applications 311

4. In the Java Applet Properties box, enter a formula that uses this field to hide the applet for a particular browser. Use the @contains(HTTP_USER_AGENT; string) formula. For example, use the following formula to hide the applet from Internet Explorer:
@Contains(HTTP_USER_AGENT; "MSIE")

Setting up shared applet resources


For large Java applets with multiple files, consider storing some of the related files as shared resources in the database. When you set up files as shared resources, all the applets can use a single copy of the file, instead of each applet storing its own copy. Then, if a file requires updating, you only need to update one file. To create a shared applet resource 1. Launch Designer and select the database where you want to set up the shared resources. Note If you do not see a Recent Databases list on the left side of Designer, drag the Design pane to the right. 2. Click Resources - Applets. 3. Click New Applet. 4. In the Base Directory field, enter the path where the Java applet files are stored. 5. Select the files you want to set up as shared resources from the Available Java Files list and click Add/Replace file. 6. Click OK and enter a name. Click OK and Domino stores all the files as a shared resource to which you can refer, using the name you entered. To include a shared applet resource 1. In the database where you created the shared applet resource, open a document and click in a rich text field. 2. Choose Create - Java Applet. 3. In the Create Java Applet dialog box: Select Import an applet from the file system or use an applet resource. In Base Directory, enter the path for the applet files. In Base Class Name, enter the name of the main class. 4. Click Locate to see all related files and shared resources for the applet. 5. Select Local Filing System in the Browse list and select the related applet files. Click Add/Replace File.
312 Application Development with Domino Designer

6. Select Shared Resources in the Browse list and select the shared resources that this applet uses. Click Add/Replace File. 7. Click OK twice.

Selecting, running, deleting, and copying applets


Selecting an applet 1. If the applet is running, you cannot select it. Choose View - Show - Java Applets Running to stop the applet. 2. Click directly to the right of the applet. 3. Use the left arrow key to select the applet. Running an applet When you open the page, form, or document containing an applet, it starts running automatically. To restart an applet after you stopped it, double-click it. Stop running applets To stop running all applets in a page, form, or document, choose View Show - Java Applets Running. Deleting an applet and its related files To delete an applet, select it and choose Edit - Delete or Edit - Clear. You cannot undo the deletion of an applet. When you delete an applet that you have imported, the related files are also deleted, unless another applet shares the files. If you want to delete shared files, you must delete them in each page, form, or document that contains an applet that uses them. Copying an applet You can copy an applet from one page, form, or document to another page, form, or document. When you copy an applet you have imported, all its related files are copied. When you copy an applet you have linked to on the Web, only the link is copied. 1. Select the applet in the page, form, or document. 2. Choose Edit - Copy. 3. Click in the page, form, or document where you want to copy the applet. 4. Choose Edit - Paste. 5. (Optional) Set applet parameters, attributes, and properties.

Chapter 11: Including Java Applets in Applications 313

Refreshing and exporting applet files


To refresh applet files Refresh the applet when you need to update existing files or add new files to the applet. 1. Select the Java applet and choose Java Applet - Refresh. 2. Select files to add or replace, and click Add/Replace File. 3. Click Refresh. To export files Exporting an applet allows you to copy all the applet files to your workstation or any other place to which you have access. 1. Select the Java applet and choose Java Applet - Export. 2. Choose the directory to export the files to and click OK. Domino exports all the applet files and creates subdirectories as needed.

Setting security for applets


To protect the security of the file system, Java security generally does not allow applets to access Notes classes. However, you can set up the applet so that it can access Notes classes, thereby allowing it to open a database and change data in it.

Setting security for applets in Notes


To set up secure access for applets that will access the file system or Notes Java classes through Notes, you must first set up an access control list (ACL), then set up an execution control list (ECL) for each user or group. The ECL controls access to the file systems and to the Notes classes on the workstation. 1. In the database storing the Java applet, choose File - Database - Access Control and set up the ACLs. 2. Choose File - Preferences - User Preferences. 3. Click Security Options. 4. Select Java applet security. 5. Enter the users and/or groups that will have access to the file system or Notes classes. 6. In the Allow list, select the options the users can use while running the Java applet. 7. Click OK twice.
314 Application Development with Domino Designer

When a user runs the applet, Domino checks for execution rights of the person or group that signed the applet. If an applet is signed by a person or group without the correct authorization, Domino alerts the user of the illegal operation. The user can stop the operation and not run the applet, trust the signer of the applet one time, or automatically add the signer to the execution control list.

Setting security for applets in Web applications


Complete these steps to set up secure access for applets that will access the file system or Notes Java classes through a browser. 1. Use CORBA to write a Notes/IIOP applet that accesses the Notes classes. 2. Import the Notes/IIOP applet in a page, form, or document, using the same procedure as for any other applet. 3. When you click Locate to Include the related applet files, make sure to include the NCSO.JAR file. 4. Import or link the Java applet that users will run. 5. Select the Java applet and choose Java Applet - Java Applet Properties. 6. In the Java Applet Info tab, select Applet uses Notes CORBA classes. Assuming your browser and server are set up correctly, you should be able to use a supported browser to view these embedded CORBA applets on a Domino server. You do not need to set alternate HTML for the CORBA applet to run. When you check the setting that specifies the applet as a CORBA applet, Domino automatically provides the HTML source code that the applet needs to make an IIOP connection back to the server. Extending the AppletBase class An applet intended for run-time access of lotus.notes.noi extends AppletBase and puts its functional code in the methods notesAppletInit() and notesAppletStart(), as shown in the sample code below, and in notesAppletStop(). AppletBase is new with Notes Release 5.0 and the lotus.notes.noi package. You do not have to distinguish between local and remote access. AppletBase will make local calls if the applet is running through the Notes client and remote calls if it is running through a browser.

Chapter 11: Including Java Applets in Applications 315

Here is an example of an applet that makes NOI calls:


import lotus.notes.noi.*; public class platform4 extends AppletBase { java.awt.TextArea ta; public void notesAppletInit() { setLayout(null); setSize(100,100); ta = new java.awt.TextArea(); ta.setBounds(0,0,98,98); add(ta); ta.setEditable(false); setVisible(true); } public void notesAppletStart() { try { // Can also do getSession(user, pwd) Session s = this.getSession(); if (s == null) { //we were not able to make the connection, warn user ta.append(Unable to create a session with the server); return; } String p = s.getPlatform(); ta.append(Platform = + p); } catch(Exception e) { e.printStackTrace(); } } }

316 Application Development with Domino Designer

Saving applet data


Various actions in a Notes document, form, or page, such as resizing or editing applet parameters, cause the applet to reinitialize to the state it was in when you opened the document, form, or page. When the applet reinitializes, it loses data the user entered and its current state. There are two methods for saving applet data: Externalization The applet stores specific information that it needs in order to return to the state it was in before it was reinitialized. Serialization The applet stores all information, for example, each variable and its current value, each class, and all header information. To maximize efficiency, it is recommended that you use externalization. Externalization There are three parameters available to direct Notes to save and reuse externalized data: ReadExternalData Directly after reinitialization, the applet uses this parameter to load data previously saved. ExternalData Any time after reinitialization, the applet uses this parameter to load data previously saved. WriteExternalData After a Notes save event, the applet uses this parameter to save current data. The data is saved as an external object with an attachment in the document that references it. The attachment is hidden and cannot be seen by the user. Usually you do not need to use both ReadExternalData and ExternalData. Use either one depending on when you want the applet to load data. Generally, the values you assign to the parameters are the same. 1. Select the Java applet and choose Java Applet - Java Applet Parameters. 2. Click Applet Parameter in the Programmers pane.

Chapter 11: Including Java Applets in Applications 317

3. If you want the applet to load data as soon as it has completed initialization, click Add and set up the following parameter: In the Parameter Name field, enter ReadExternalData and click OK. In the Parameter value window, enter the value for ReadExternalData. Its value is the name of a file that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata

4. If you want the applet to load data at some other point after initialization, click Add and set up the following parameter: In the Parameter Name field, enter ExternalData and click OK. In the Parameter value window, enter the value for ExternalData. Its value is the name of a file that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata

Notes appends the value with the entire URL of the data file. 5. If you want the applet to save data at the end of the session, click Add and set up the following parameter: In the Parameter Name field, enter SaveExternalData and click OK. In the Parameter value window, enter the value for SaveExternalData. Its value is the name of a file that is attached to the page, form, or document where the applet is stored. For example,
mydata

If the file attachment does not exist, Notes creates it and stores the data in it. Example HTML code to set up parameters:
<PARAM NAME="readexternaldata" VALUE="mydata"> <PARAM NAME="writeexternaldata" VALUE="mydata">

318 Application Development with Domino Designer

Serialization There are two parameters available to direct Notes to save and reuse serialized data: Object The applet uses this parameter, a standard HTML parameter, to load (using Java VM and VM) previously saved applet data in the serialized object. Object must exist before the applet attempts to load it, or the operation fails. WriteObject After a Notes save event, the applet uses this parameter, a Notes extension, to save the data. The data is saved as a serialized object in a hidden attachment to the document. The user cannot see the attachment. 1. Select the Java applet and choose Java Applet - Java Applet Parameters. 2. Click Applet Parameters in the Programmers pane, and then click Add. 3. To load the previously saved data, enter the following in the Parameter Name field and click OK:
Object

4. In the Parameter value window, enter the value for Object. Its value is the name of a file that contains the previously saved state information from the WriteObject parameter. This file is attached to the page, form, or document where the applet is stored. For example, enter:
mydata

5. To save the applet data, click Add, enter the following in the Parameter Name field, and click OK:
WriteObject

6. In the Parameter value window, enter the value for WriteObject. Its value is the name of the file that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata

Example of HTML code to set up parameters:


<PARAM NAME="object" VALUE="mydata"> <PARAM NAME="writeobject" VALUE="mydata">

Chapter 11: Including Java Applets in Applications 319

Details Although you can set up an applet for both externalization and serialization, Notes cannot support both. An error is not reported, but one applet cannot do both. In the Java applet itself, you must write methods to support the Java Externalize interface. If the applet does not have these methods, you can still run the applet. However, the data cannot be saved, even if you set up the parameters. If you save data, keep these points in mind: If the applet is imported in a subform, the data from the subform has precedence over the data in the form. Therefore, modifying an applet in a subform modifies all of the forms that include that subform. Data from an applet contained in a document takes precedence over the data stored in a form or subform. If you imported the applet in a document and you are saving data, the data file will be copied if you export the applet. If you imported the applet in a form, the data file will not be copied if you export the applet from a document you created with the form.

Tips and troubleshooting for Java applets


When the applet runs, the status bar displays messages such as Loaded <applet-name>, Initialized <applet-name>, and Started <applet-name>. If the applet does not run as expected, a dotted gray rectangle is displayed. The rectangle means the applet did not load properly. Review the sections below and use File - Tools - Show Java Debug Console to examine the applet and determine the problem.

Troubleshooting an applet that is not running


If the applet is linked to a Web site, check that your Web proxy is running. Get the name of your Web proxy from your Location document. If you are running Windows, go to the DOS prompt and use the ping command followed by the proxy name to determine if your connection is valid. If the ping command returns an error rather than a reply, contact your system administrator for help restoring your Web proxy. Check that you included all the necessary applet files. Choose Java Applet - Refresh to add additional files to the applet. To make sure you have all the files, select All for File Types and click Select All to include everything.
320 Application Development with Domino Designer

Check that you entered the correct name for the applet files. Java is case-sensitive, so the file names must match exactly. Make sure you correctly specify the parameters required by the applet. Choose File - Tools - Show Debug Java Console and view the messages reported by the Java applet. Check for missing parameters and add in parameters that are required.

Accessing resource files


Java applets frequently use resource files such as images and audio files. There are three common ways that applets access these files: By specifying a full URL for the file, for example, http://www.someplace.com/image.gif. By using the applet class getDocumentBase method to construct a URL relative to the location of the document in which the applet is found. By using the applet class getCodeBase method to construct a URL relative to the code base of the applet, that is, the location from which the applets files were loaded. Depending on what method you use, Domino may not be able to locate resource files for the applet. The getCodeBase method is the most reliable method for specifying resource files. If you experience problems with applets not finding resource files, modify your applet to use getCodeBase. Recompile the files and choose Java Applet - Refresh to replace these files in the document. Specifying a full URL If your applet specifies a full URL to locate a resource file, for example, getImage(http://www.someplace.com/images, image.gif), the applet attempts to find the file at that URL. This usually works when running applets within the Notes client in a document served by a Domino server, as long as you correctly configure your Notes client to access files on the Internet. Similarly, you can access images attached to Notes documents by constructing the Domino URL to include a $FILE (for example, getImage(http://www.someplace.com/database.nsf/MasterView/862..12 E/$FILE, image.gif). As above, the Notes client must be able to access the Domino server in order for an applet running in the Notes client to be able to access this file.

Chapter 11: Including Java Applets in Applications 321

The drawbacks of specifying a full URL for an applet resource file are that it may be slow to access this file through the Internet and not all Notes clients are set up to directly access the Internet. Also, this course of action assumes that the location of this file will not change. If these are not concerns, this is a reliable way to access resource files. Using getDocumentBase The least reliable means of specifying resource files is the getDocumentBase method. The getDocumentBase method of specifying resource files returns the base URL (that is, the full document URL minus the document file name) of the document in which the applet is located. For example, if an applet is running in a document at:
http://www.someplace.com/test/example.html

the getDocumentBase method returns a URL specifying:


http://www.someplace.com/test

Some applets use this method to specify a URL for resource files, for example, getImage(getDocumentBase(), image.gif). Using the above URL as an example, the applet would be looking for the image file at the URL
http://www.someplace.com/test/image.gif

Note, however, that the Domino URL for a document does not simply refer to a file; instead, it is a command for the Domino server to generate the HTML representing a document. If you use the getDocumentBase method as a Domino URL, you get unexpected results. For example, suppose you linked an applet with the following Domino URL:
http://www.someplace.com/database.nsf/MasterView/862..12E?Open Document

In this case, using the getDocumentBase method in conjunction with the getImage call returns:
http://www.someplace.com/database.nsf/MasterView/image.gif

The applet cannot find the file because the document ID is gone and the image is an attachment to a document, requiring a $File qualifier as part of its name. Because the documents ID has been removed (and since the image is in an attachment in the document and thus needs $FILE to qualify the file name), the requested image cannot be found by the applet.

322 Application Development with Domino Designer

Using getCodeBase The most reliable means of specifying a resource file for an applet is the getCodeBase method. The getCodeBase method returns the base URL from which the applet was loaded. The codebase for an applet can be specified by the CODEBASE attribute in the APPLET tag. When Domino generates the HTML for an applet which has been inserted into a Notes document, it generates a full URL for the CODEBASE attribute. For example, given the example above, the getCodeBase method returns:
http://www.someplace.com/database.nsf/MasterView/ 862..12E/$FILE

When used in conjunction with resource calls, such as getImage calls, getCodeBase correctly specifies the resource file. For example:
getImage(getCodeBase(), "image.gif")

yields the following URL when the applet is served by Domino:


http://www.someplace.com/database.nsf/MasterView/ 862..12E/$FILE/image.gif

This results in a URL that allows the applet to successfully find the file. Modifying parameter values to locate resource files Some applets include parameters that refer to resource files or to directories containing resource files. For example, an applet may include a parameter specifying a file for use as a background image or a directory for audio files. You may need to edit the applet so that these parameters are relative to the codebase, rather than to the document base. If you are not building the applet yourself, for example, if you are linking to an applet on the Internet, or if you obtained a set of .class files without the source code, you might need to edit a parameter value after inserting the applet into a form or document. In that case, prepend the string $notes_codebase to the parameter value. For example, instead of using images/image.gif, use $notes_codebase/images/image.gif as the parameter value. Domino converts any occurrences of the $notes_codebase string in a parameter into the codebase for the applet. The parameter value $notes_codebase/images/image.gif is therefore converted by Domino to:
http://www.someplace.com/database.nsf/MasterView/ 862..12E/$FILE/images/image.gif

Since this effectively means that you are providing a full URL when specifying the parameter value, the getDocumentBase method in the applet is overridden, and the applet will be able to find the resource file.

Chapter 11: Including Java Applets in Applications 323

Chapter 12 Including OLE Objects in Applications


This chapter illustrates ways to design applications that use OLE technology to integrate data from other applications.

Designing applications using OLE


Using OLE (Object Linking and Embedding) and OLE-related tools lets you extend the capability of Designer. OLE technology lets you integrate data from other applications, such as spreadsheets, graphics tools, and other data sources, into your application. For information on scripting OLE objects and using OLE custom controls, see the Programming Guide. Note Some of the OLE-based technologies available in Domino are platform-dependent. Windows offers the greatest range of options for sharing information and launching objects. Unless otherwise noted, activities covered in this chapter apply only to Windows. Using OLE and OLE-related tools in Designer, you can: Link and embed objects in forms Using object linking and embedding (OLE), you can design a form that displays the same object in every document created from that form. When you link an object, every document created from the form refers to the source of the link. When you embed an object, the object itself appears on every document created from the form. Linking and embedding objects is supported for Notes applications only. Launch objects automatically Using object linking and embedding, you can design a form that automatically launches an embedded object or a new object created using any OLE-registered desktop application. The autolaunch can occur when users create, edit, or read a document based on the form. Autolaunch helps create a smooth workflow involving multiple applications. It also allows users who are familiar with other products to work within those applications without leaving your Notes application. This autolaunch feature is not available for Web applications.
325

Add custom controls to a form If you use Notes with Windows NT or Windows 95/98 and have OLE custom controls installed, you can create custom control objects in documents or on forms. An OLE custom control, also known as OCX or as ActiveX, is a small, self-contained software module with its own data. Lotus ComponentsTM, which are examples of controls, allow you to use other Lotus products, such as a Lotus spreadsheet or chart, while continuing to work in a Notes database. For information on creating and using the Lotus Components, see the online Help that comes with the Lotus Components software or go to the Lotus Web site at http://www.lotus.com. Your organization may create OLE custom controls from various manufacturers and use the controls in Notes. Some OLE custom controls may not provide online Help for their application. Set up forms to exchange field information with other Notes documents You can create forms in Designer that automatically share information with documents created in other OLE-registered applications. Then, when users modify the contents of a field in a Notes document, the changes are automatically made to the corresponding fields in the other applications document. Data exchange can occur in both directions: users can edit fields in Notes or the other application, and the modifications are automatically exchanged. OLE-registered applications must support NotesFX in order to use field exchange in Notes. This feature is not available for Web applications. Publish an action This is the most powerful of the OLE-based tools because it is the most flexible. You can automate complicated or repetitive tasks that involve multiple operations across multiple applications. You design an action using formulas or scripts, and then publish it. The action appears on the Action menu in any Notes/FX 2.0-enabled application. This feature is not available for Web applications. Embed JavaBeans JavaBeans are self-contained objects, similar to ActiveX controls, that can be used with other beans to create applications. Like ActiveX controls, you can embed JavaBeans into Notes documents and rich text fields, forms, subforms, and pages, and then attach scripts and events to them. You must install the Java Runtime Environment (JRE) before you can embed JavaBeans in a Notes document or in a Designer form.

326 Application Development with Domino Designer

Linking and embedding objects in forms


Object linking and embedding (OLE) is a powerful design tool. When you link or embed an object in a form, every document created from the form displays the object. Whether you link or embed an object depends on how the form will be used. Linking maintains the object in the source application and displays the object in the host application, which in this case is the Notes form. For example, a form might contain a 1-2-3 spreadsheet that you update frequently. The advantage to linking is that you can maintain control over the source. When you update the object in the source application, all links to the object automatically update. The disadvantage to linking is that all users must have access to the file containing the object, as well as the application used to create it. In this example, the users need the spreadsheet file and 1-2-3. Embedding an object allows you to place the object in a form. The object lives in the form, and users can modify and update the object from the form. For example, if you embed a graphic in a form, users need a compatible version of the source application to view the graphic. Designer access is required to modify the graphic. To link an object in a form To link to an object, it must already exist in the source application. 1. Use a source application that supports object linking and embedding (OLE) to create an object. 2. Copy the object to the Clipboard. 3. Open the form in Designer, click where you want the object to appear, and select Edit - Paste Special. 4. Save and close the form. To embed an object in a form You can create an embedded object from within Designer. 1. Click where you want the object to appear on the form, and then select Create - Object. Designer lists the available applications that support OLE. This list of applications appears in a list entitled Object type. 2. Choose an application. Designer will launch the application into in-place edit by default if the application supports this; otherwise, Designer will open the application. 3. Create data in the application.

Chapter 12: Including OLE Objects in Applications 327

4. If you are using in-place edit, click outside the OLE application to return the focus to Designer. If Designer originally opened the application, exit the application. 5. Save and close the form. For more information on creating objects, see Notes Client Help. OLE and LotusScript To build on the power of OLE, use LotusScript to create or enhance workflow applications. You can use LotusScript to create, manage, and update objects within Notes documents. For more information on using LotusScript with OLE objects, see the Programming Guide.

Adding OLE custom controls to a form


You can add a custom control, such as a Lotus Component, to a form to make the control available in documents created from the form. After inserting the control, you can edit properties that control its display. To create an OLE custom control object 1. In a rich text field or on a form, choose Create - Object. 2. Do one of the following: Select Create a new object. In the Object type list, choose a custom control. The custom controls have starburst icons next to them. Select Create a new control. In the Object type list, choose a custom control and click the Add control button. 3. Click OK. Note Some custom controls do not display in the Create Object dialog box. You cannot use this method to insert these controls. Instead, use LotusScript to insert them because these types of controls do not support a UI and are only programmable. To see online Help for Lotus Components 1. In a rich text field or on a form, select a Lotus Component object. 2. Choose a command from the Help menu, or press F1. To access an existing control, select it. When a custom control is active, the Help menu is a combination of Designer (File and Applet) and the custom control. The control may include one menu item for itself for example, Spreadsheet for a spreadsheet control and Help. The controls Help is substituted for Designer Help.

328 Application Development with Domino Designer

Use the Applet menu choice to: Copy and cut the entire object. Use the Edit menu to copy and cut selected text in the object. Access Notes properties for the control, including the name of the control. Access the controls own properties. Set the controls mode. Freeze and unfreeze the controls events. If a control is active when you embed it in a form, a list of events appears in the Info List of the Programmers pane. You can attach scripts to these events. For information on attaching scripts to a custom control, see the Programming Guide.

Modifying a form to size an embedded object


If an objects server application supports OLE2 in-place editing, Designer can expand the object when you edit it. 1. With the form in Edit mode, click the object. 2. Choose Edit - Properties or select the dynamic menu presented for the OLE application. For example, clicking a Lotus 1-2-3 object adds the menu choice Workbook. Select Workbook, then Object Properties. 3. In the Properties box, choose Size object to window. When you choose Size object to window, the following occurs: When a user uses this form to create a document, the user must double-click the object to display it in the full application window. If the document contains information below the object, the user will not be able to see that information. 4. Close the Properties box. 5. Save and close the form.

Chapter 12: Including OLE Objects in Applications 329

Modifying a form so that it sizes an OLE custom control or JavaBean


1. Open the form and click the custom control. 2. Choose Applet - Object Properties. 3. Do one of the following in the Properties box: Choose Size object to window. Choose Size object below field. 4. Close the Properties box. 5. Save and close the form. When you use the form to create a document, the control expands, based on the property you chose. Note the following: The property you choose takes effect after you save and close the form or document. If you choose Size object to window, the following occurs: When a user creates a document or opens an existing document in Edit mode, the custom control automatically expands to fill the entire application window. If the document contains information below the custom control, the user cannot view that information while the custom control is expanded. If you choose Size object below field, the following occurs: When a user creates a document or opens an existing document in Edit mode, the custom control automatically expands to fill the area of the Notes window below the layout region. If the document does not contain a layout region, the custom control expands to fill the entire application window. If the document contains information below the layout region, the user cannot see that information while the custom control is expanded. If the document contains two or more layout regions, the custom control expands below the first layout region. The user cannot see the other layout regions.

330 Application Development with Domino Designer

Modifying a form to run a custom control or JavaBean in Read mode


1. Open the form and click the custom control. 2. Choose Edit - Properties or Applet - Object Properties. 3. Choose Run object when reading document in the Properties box. 4. Close the Properties box. 5. Save and close the form. When a user opens a document, the object automatically launches in Read mode. The user can change the object and print the changes, but cannot save the changes without first putting the document into Edit mode. Note This option is available only for custom controls and JavaBeans. Some custom controls and JavaBeans do not render anything for display in Read mode. With this setting, you can force the custom control or JavaBean to display in Read mode.

Letting documents update objects created by forms


You can create an object or custom control in a form and let documents created with the form update the object or custom control. A user can change the OLE object or custom control and save those changes with the document. The OLE object or custom control in the form does not overwrite the revised OLE object or custom control in the document. 1. Open the form and click the object or custom control. 2. Choose Edit - Properties. 3. In the Properties box, choose Update object from document. 4. Close the Properties box. 5. Save and close the form.

Launching objects automatically


You can have a form automatically launch (autolaunch) an embedded object or a new object when a user creates a document or opens one for reading or editing. A new object is one that is blank until users add data. The user can change the embedded object and add data to a new object directly in the application that created the object. The Notes document automatically displays the changes. Note that autolaunch is not available in Web applications.

Chapter 12: Including OLE Objects in Applications 331

When you design a form that autolaunches an embedded object, the object must be the first OLE object in the form. To autolaunch other objects embedded in the form, you must write a script. Users can launch embedded objects manually, except in documents that open as modal dialog boxes. If you create an object in a rich text field on a form, when users create a document, the object launches. If you dont create the object in a rich text field, when users create a document, Notes launches the first object that appears in the form. When users subsequently open the document for reading or editing, the first object in the document launches. The following are ways to launch OLE objects: Launch an object automatically The object can be a spreadsheet, a word-processing document, a graphic presentation, a database, or a multimedia object. You can autolaunch objects created in any registered OLE application. Launch a new object automatically A new object is blank until users add data. You can autolaunch a new object in any registered OLE application. Launch an object in-place or out-of-place The object launches in-place if it launches within the Notes document. The object launches out-of-place if it launches in the application that created it. Define the conditions under which objects are launched The object launches only when it is created or when it is opened in Read or Edit mode. Use the form open in a modal dialog box to create documents The object launches into a modal dialog box that the designer can customize to allow specific actions users can take with the object. Hide the Notes document You can hide the Notes document when the object is launched or when the launched object is closed. Hide the original embedded object in documents You can hide the original embedded object and display only the most recent, updated version of the object in a document.

332 Application Development with Domino Designer

Designing a form that launches an object automatically


1. Open the form containing the embedded object you want to launch automatically. 2. Choose Design - Form Properties. 3. Click the Launch tab. 4. Select First OLE object in the Auto Launch box. 5. (Optional) To create the object in a rich text field, do the following: Position the insertion point where you want to create a field to display the object, and choose Create - Field. Enter a name for the field. Select Rich Text in the Type box. Select Form in the Properties for drop-down list. Click the Launch tab. Select the name of the rich text field in the Create object in field box or choose First Rich Text Field. Select None if you do not want to display a current representation of the object in documents. 6. Close and save the form. Displaying the object in documents created using the form When the object is autolaunched, modified by the user, and saved, it is displayed in the document in the field you specify in the Create object in field box. You can specify First Rich Text Field to display the saved object in the first rich text field in the document. To display the current representation of an object in the document, store the form with the document. This causes updates to the object to replace the original embedded object in the document. Storing the form with the document uses a large amount of disk space and processing time. To store the form with the document, open the form, choose Design - Form Properties, click the Defaults tab, and select Store form in document. Objects and full text search Full text searches can include embedded objects and attachments. When a full text search finds a match in an embedded object or attachment, the object or attachment opens, but the matching word or phrase does not appear highlighted.

Chapter 12: Including OLE Objects in Applications 333

Nested objects If the OLE server application is also a client application, an object in a Notes document may have other objects within it. In this case, when an object is updated, the object in the Notes document reflects the changes even if they were made in an other application. When an object that contains other objects is autolaunched, only the application that created the object embedded in the Notes document is launched. Examples: Designing a form that launches an object automatically You need a Spring product line database that sales representatives use to create custom presentations from a standard set of slides. Create a Sales Presentation form and embed a Freelance Presentation file containing the standard slide presentation. Specify the Freelance Presentation object to autolaunch only when a document containing it is created. When you use the Sales Presentation form to create a document, Freelance Graphics launches and you save the object without modifying it. Then use the name Standard Presentation to save the Notes document. You now have a document stored in the database and accessible by sales representatives all over the world, containing standard slides for a sales presentation. Sales representatives who want to modify the presentation use the Sales Presentation form to create a new document. The Freelance Graphics object launches automatically, and the sales representatives can customize the slide presentation. They then save the object, and specify a new name when they save the Notes document containing it. Their custom version of the slide presentation is now in the database, where other sales representatives can access it.

Designing a form that launches a new object automatically


1. Open the form. 2. Choose Design - Form Properties. 3. Click the Launch tab. 4. Select the OLE server application in the Auto Launch box. The list includes all registered OLE server applications on your hard drive. 5. Position the insertion point where you want to create the field that will display the object, and choose Create - Field. 6. Enter a name for the field.

334 Application Development with Domino Designer

7. Select Rich Text in the Type box. 8. In the Form Properties box, click the Launch tab. 9. Select the name of the rich text field in the Create object in field box. 10. Close and save the form. When a document autolaunches a new object, the application initially displays an empty object. The user adds the appropriate data, and then closes and saves the object. The new object is embedded in the rich text field you specify in the Create object in field box. To display the object in the first rich text field in the document, you specify First Rich Text Field. Then when a user reads or edits the document, the object in the first rich text field launches automatically. If the document was opened in edit mode, this allows the user to enter data or make changes. Nested objects If the OLE server application is also a client application, an object in a Notes document may have other objects within it. In this case, when an object is updated, the object in the Notes document reflects the changes even if they were made in another application. When an object that contains other objects is autolaunched, only the application that created the object embedded in the Notes document is launched.

Launching an object in-place or out-of-place


By default, objects are launched in-place, so that the object can be edited right in Notes. If the object does not support in-place editing, then the object will be launced out-of-place, so that focus shifts to the application used to create the object and Notes goes into the background. Only applications that support OLE2 can launch in-place. Applications that support OLE1 always launch out-of-place, regardless of the Launch in place property. Objects that are embedded in the form as icons always launch out-of-place. Note Autolaunching is not supported on the Macintosh. 1. Open the form containing the object. 2. Choose Design - Form Properties. 3. Click the Launch tab. 4. Select Launch in place, or deselect it to launch out-of-place. 5. Close and save the form.

Chapter 12: Including OLE Objects in Applications 335

Specifying the event that causes an object to autolaunch


You can design a form so that an object autolaunches when a user creates, edits, and/or reads the document. A new object autolaunches when a user creates a document. By default, existing objects autolaunch each time a user reads or edits a document containing an object. 1. Open the form containing the object. 2. Choose Design - Form Properties. 3. Click the Launch tab. 4. Select Creating, Editing, and/or Reading in the Launch when box. 5. Close and save the form. Details You can control whether the object in the first rich text field in a form autolaunches when a document is created, edited, or opened. If the form youre designing autolaunches a new object, make sure the Launch when setting includes Creating, because this is the only event that launches a new object. After the user creates the document, the new object is saved with the document. Other Launch when settings, such as Reading or Editing, take effect when a user subsequently opens the document. If you set the form to Automatically enable Edit mode (on the Form Defaults tab of the Form Properties box), make sure the Launch when settings are compatible. For example, if you design the form so that the object launches only when users open the document in Read mode and you set the document to enable Edit mode automatically, the document always opens in Edit mode and the object never autolaunches. Examples: Specifying the event that causes an object to autolaunch Design a form to distribute financial information contained in a 1-2-3 object. In the form, you embed a 1-2-3 object that is a template for entering financial information. Create a rich text field in the form, and specify that the field display the object. Also specify that the object autolaunch only when a user uses the form to create a document. When a user uses the form to create a document, the 1-2-3 object autolaunches so the user enters the information in 1-2-3. The user closes and saves the 1-2-3 object, and then closes and saves the new document. When people read the document, the 1-2-3 object is visible in the rich text field, but the object does not autolaunch. To edit the object, the user opens the document in Edit mode and double-clicks the object to launch it.

336 Application Development with Domino Designer

Designing a form for documents that open as modal dialog boxes


To control what the user can see or do when creating, editing, or reading a document, design a form to open as a dialog box. 1. Open the form. 2. Choose Design - Form Properties. 3. Click the Launch tab. 4. Select Present document as modal dialog. 5. Close and save the form. When users create or open a document that opens in a dialog box, they cannot access Notes menus. Instead, they have access to a small set of actions that include: Entering or modifying data Launching the first embedded OLE object by clicking the Launch button on the dialog box Choosing a command from the Action menu at the bottom of the dialog box As the designer, you can control the list of commands available on the Action menu. For more information about showing form actions, see Adding Automation to Applications.

Designing a form to hide the Notes document


To allow users to move seamlessly from the Notes view level to an autolaunched application and back again, design a form to hide the Notes document. You can hide the Notes document when users create, read, or edit the document. 1. Open the form. 2. Choose Design - Form Properties. 3. Click the Launch tab. 4. In the Hide when list, select an option. (Click the option again to deselect it.) 5. Close and save the form.

Chapter 12: Including OLE Objects in Applications 337

You can design a form to hide the Notes document during any of these activities: Users create a document (Opening Create). Users open a document to edit it (Opening Edit). Users open a document to read it (Opening Read). Users close a document after creating it (Closing Create). This option is available only if Opening Create is selected. Users close a document after editing it (Closing Edit). This option is available only if Opening Edit is selected. Users close a document after reading it (Closing Read). This option is available only if Opening Read is selected. Mixing Hide/Show options You can design a form that hides the Notes document in some circumstances and shows it in others. Use this type of form when document creators, editors, and readers play different roles in maintaining the information in the Notes database. Hide Notes documents when: The main focus of the document is the object, and users dont need to fill in anything else. The form contains only one object. Users arent familiar with Notes and want to work in a familiar application. The Notes database is functioning solely as a container system for other application files. All users have access to and can launch the other application and always work in that application. Show Notes documents when: Readers need to see more than the data object itself. The form contains multiple objects. Revising the data in the object is optional; therefore, you dont need to launch every time the Notes document opens. Users who create and edit documents need to fill in other fields on the form. Some users have operating systems, such as OS/2, that dont support OLE objects, but they still need to read the information or edit other fields in the Notes document.

338 Application Development with Domino Designer

Examples You create a report-tracking database that allows users to use 1-2-3 to create and update their own expense reports. When users create or update expense reports, they dont need to see the Notes document; instead, they want to autolaunch the expense report object in 1-2-3. To design a form that mirrors your users workflow, create an Expense Report form, embed a worksheet object in the form, and set the form properties to automatically launch the worksheet. In the Hide when box, you select Opening Create, Closing Create, Opening Edit, and Closing Edit. When users choose Create - Expense Report, Notes automatically starts 1-2-3 and launches the embedded worksheet object. Users enter information directly into the 1-2-3 worksheet object and never see the Notes document. When users complete the expense reports and quit 1-2-3, the worksheet object embedded in the form updates, users are returned to the view level in Notes. If users want to edit their expense reports, they open the document in edit mode, and 1-2-3 autolaunches. When they close 1-2-3, users are returned to the view level of Notes. Information from the expense report worksheet appears in the Notes document or in the Notes view. The Notes database contains all of the expense reports.

Hiding an embedded object in a document


You embed an object in a form for autolaunch so that users can make modifications to the object. You then specify a rich text field to display the latest representation of the object. If you want to display only the latest version not the original version of the object, you must design the form to hide the original embedded object. After the user makes changes to the object and returns to the document, only the changed version appears in the document. 1. Open the form containing the object you want to hide. 2. Select the object you want to hide. 3. Open the objects properties box. 4. Click the Hide When tab. 5. Select one or more options for hiding the object. 6. Close and save the form.

Chapter 12: Including OLE Objects in Applications 339

Publishing actions
When you publish an action, you make it available on the Action menu in any open OLE server application. For example, you might automate a document review process so that a Notes user opens a document that autolaunches a Word Pro file. After editing the file, the user clicks the Send to Next Reviewer menu choice in Word Pro, which routes the document containing the Word Pro document to the next user. By publishing actions, you seamlessly coordinate tasks between applications. From a designers point of view, publishing actions expands the scope of what you can do with a flow of work and enhances your ability to control that flow. Teamed with autolaunching, publishing actions allows you to focus or limit user-access to commands, thereby controlling the flow of work. By simplifying and automating multi-step tasks, you improve the security of your system and reduce the chance of user error. Actions allow you to integrate file creation and storage in other desktop products with the document sharing, storage, security, and management tools of Notes. Actions can incorporate functions, @commands, and LotusScript. Notes also supplies a number of simple actions, such as Move to Folder, which allow you to incorporate useful actions in your form design without programming in LotusScript. For information on actions, see Overview of Automation.

When the action executes


On the Advanced tab of the Action Properties box, you can specify what happens when an action runs. Select Close OLE object and return to Notes to close the object, save any changes made during the OLE session, and return to Notes. Select OLE object remains open if you want the focus to remain with the OLE object. This property is useful if users need to choose more than one action before returning to Notes. When designing actions, keep in mind the state of the application when returning to Notes. For example, if you use the autolaunch feature with an action, decide whether you want users to return to Notes, whether you want the Notes window hidden, whether users are in a document or a view, and whether the document has been saved or is new. Write documentation or field help in the form to provide guidance to users.

340 Application Development with Domino Designer

Bring document window to front


On the Advanced tab of the Action Properties box, choose the property Bring document window to front if you want the focus to return to Notes without closing the OLE object. By shifting the focus back to Notes, you provide the opportunity for user-input in Notes. When you use this property, remember that the OLE object has not been saved, unless you explicitly saved the object as part of the action. Therefore, you may have to provide a way for users to return to the object to save it. Note The Bring document window to front property applies only when the document window in Notes has not been hidden.

Steps in publishing an action


1. Open the form. 2. Choose View - Action pane to display the Action pane. 3. Double-click the action you want to publish. 4. Choose Design - Action Properties. 5. Click the Advanced tab. 6. Select Publish Action with OLE object. 7. Select a property that controls what happens after a user chooses an action. 8. (Optional) Select Bring document window to front to change the default setting. 9. Close and save the form. For information about creating an action, see Adding Automation to Applications. If actions do not get published even after you select Publish action with OLE object, make sure Notes/FX 2.0 is enabled. Choose Design - Form Properties and click the Defaults tab. The Disable Field Exchange check box should not be checked.

Chapter 12: Including OLE Objects in Applications 341

Examples A Word Pro document needs to be routed for approval. The Notes form you create has an embedded Word Pro document set to autolaunch when edited and an action called Send to Next Reviewer. When a user opens the Notes document in Edit mode, the Word Pro document automatically launches. When reviewing the Word Pro document, the user selects the Send to Next Reviewer action from the Action menu in Word Pro. This action sends the Notes document to the next reviewer and closes the object. To provide other routing options, you can add the actions Ready for Next Reviewer, Return to Previous Reviewer, and Archive Document to the Notes form.

Exchanging data using Notes/FX


Notes/FX is supported only for Notes applications. Using Notes/FX, you can design forms so that field contents in an OLE server application file automatically appear in corresponding fields in a Notes document, and vice-versa. Depending on the type of field, you can update the contents from Notes or from the other OLE application. To exchange data, there must be a one-to-one correspondence between the shared fields. Both the OLE server application file and the Notes form must contain the same shared fields. A Notes/FX field can be: One-way Two-way User-defined One-way fields These fields provide information for exchange in only one direction. One-way fields supply information about a file for example, file size and creation date. These fields exist by default in the OLE server application; you create the corresponding fields in your Notes form. For example, Word Pro documents have a field called SizeInK, which contains the size of the Word Pro document in kilobytes. To exchange the data in this field with a field in a Notes form, create a field named SizeInK in the Notes form. After you set up field exchange, changes to the Word Pro field appear in the Notes field; however, changes made to the Notes field do not affect the Word Pro field.

342 Application Development with Domino Designer

Two-way fields These fields provide information for exchange in two directions that is, from Notes to the OLE application and from the OLE application to Notes. When you change the contents of the field in either application, both fields update. Fields defined as two-way exist by default in many OLE server application files; therefore you create corresponding fields in your Notes form. For example, the Document Description field in a Word Pro document corresponds to the Subject field in a Notes document. After you set up field exchange, changes to one field automatically appear in the other field. The fields must have the same name. User-defined fields These fields exchange data in two directions, but you must create these pairs of fields, since they do not exist by default in the OLE server application file. User-defined fields usually exchange working data, such as text or numbers. You create and name these fields in the OLE server application file and in the Notes form. For more information about fields in OLE server applications that exchange data with Notes, see the documentation for the OLE server application.

Preparing a form to exchange data


Data is exchanged on a field-by-field basis. Every Notes/FX 2.0 field in a Designer form must have a corresponding field with the same name in the other application file. Note If you are using a form copied from a Designer template, fields may already be set up for field exchange. Enabling field exchange 1. Open the form and choose Design - Form Properties. 2. Click the Defaults tab. 3. Make sure Disable Field Exchange is not checked. 4. Close and save the form. Note You can disable Notes/FX 2.0 field exchange without removing the Notes/FX fields from the form by checking the Disable Field Exchange property.

Chapter 12: Including OLE Objects in Applications 343

Setting up field exchange 1. Open the other application file. 2. Write down the name of each field you want to exchange and close the application. 3. In Designer, open the form you want to prepare for Notes/FX field exchange. 4. Embed the object containing the fields you want to exchange. 5. Choose Create - Field. 6. Give the field the same name as the corresponding field in the other application. 7. Close and save the form. Examples: Exchanging data The following table lists one-way and two-way fields found in most Lotus applications. For a complete list, see the documentation for the application.
Field name LastRevisionDate NumberOfEdits EditingTime SizeInPages SizeInK DocumentClass Subject Categories Data type Time Number Number Number Number Text Text Text (allow multi-values) Contents Date and time the file was last revised Total number of revisions to a file Total time the file was open Number of pages in the file Size of the embedded object in kilobytes OLE class name of the application embedded in Notes Description of the document Keywords that Notes uses to categorize documents

Exchanging data for an expense form You create a form to file and distribute trip reports. The reports contain descriptions of the important business aspects of the trip, as well as the total expenses. You record expenses in a Lotus 1-2-3 expense report template. You want the total expenses of the trip to appear automatically in the Notes document.

344 Application Development with Domino Designer

In the 1-2-3 template, create an expense report. In one cell enter Total_Exp. Now create a range name for this cell and name it Total_Exp. Because this is a custom Notes/FX field, you need to tell 1-2-3 to use this range name for Notes/FX. Select File - Workbook Properties and then select the Notes/FX Fields tab. Select the New Field button and then select the range name Total_Exp. Select OK twice. The row below the cell entitled Total_Exp will hold the actual data that is exchanged between Notes and 1-2-3. Save and close this 1-2-3 Workbook. In Designer, create a form called Trip Report and embed the recently created 1-2-3 expense report. The Trip Report form contains text fields for entering information about the trip. At the bottom of the form, use the text The total expenses for the trip were: to label a field area and create a numeric field named Total_Exp which corresponds with the name of the field in the 1-2-3 expense report template.

When users use the form Trip Report to create reports, the total expenses are automatically inserted in the document.

Chapter 12: Including OLE Objects in Applications 345

Chapter 13 Restricting Access to and Securing Parts of an Application


This chapter describes Designer features for limiting access to parts of an application. It does not provide a comprehensive description of Designer security features. For more information on security, see Managing Domino Databases and Administering the Domino System.

Security in an application
Designer offers a multi-layered approach to security. You can secure fields, sections, forms, views, databases, servers, and domains. Securing servers and controlling access to a domain is the responsibility of the server administrator. As a database designer, you can control who has access to an application you create, right down to the contents of a single field. You can also control access to application-specific features, such as the database design and agents that run on a database. The features you use determine how secure your application is. The database access control list and encryption features provide true security. Creating form access lists and hiding design elements let you hinder access but are not true security features. To restrict or limit access to parts of a database, use these features: The database access control list (ACL) specifies who can or cannot access the database. For users who can access a database, access levels and roles determine the specific actions they can perform for example, creating or deleting documents. Note that, if the Web user is being authenticated with Basic authentication (that is, name and password), the Advanced section of the ACL lets you specify a maximum access setting for Web users. Even if you explicitly give Web users higher access, they never have an access level greater than what you specify as the Maximum Internet name & password access.

347

If the Web user is being authenticated using SSL Client certificates, then the Maximum Internet name & password access field does NOT apply to them. These users have the full access granted to them in the ACL. In other words, if the access list says that they have Manager access, they truly have Manager access to the database and not the access specified in the Maximum Internet name & password access field. The Secure Sockets Layer (SSL) is a security protocol that protects data by encrypting it as it passes between servers and Web clients. The SSL must be set up at the server as well as set for a database. Form access lists, in conjunction with the database ACL, control who can read or edit all documents created from a form. Document access fields (Readers and Authors fields), in conjunction with the database ACL, control who can read or modify specific documents. Encryption allows you to secure information for Notes clients at the field level. You can encrypt the contents of any field so that only readers who have the encryption key can access the message or field. Database managers can encrypt an entire database. Encryption is not supported in Web applications. Electronic signatures confirm that documents or document sections mailed from one user to another are not tampered with before reaching their destination. To restrict access to parts of the design, use these features: Restrict who can create agents and where the agents can run. Most users can create private agents to run on local databases; some users can also create shared agents that run on servers for use by other users. Secure the design of a database to prevent users from changing design elements. For information on restricting agents, see the topic Agents. For information on securing a database using the access control list, see Managing Domino Databases. For information on setting up the SSL, see Administering the Domino System.

348 Application Development with Domino Designer

Controlling access to a database during design


Every database has an access control list (ACL) that defines who has access to the database and describes the activities they can perform. While you are designing the database, strictly limit access so that only you, other designers, and the database manager have access to the database. When the database is ready to be released, the database manager can adjust access control settings to provide general access to the application.

Keeping a database private during development


If the database you are developing is stored on a server, take these extra precautions so users arent able to see the database until it is ready. When the database is ready to be released, the database manager can adjust these settings to make the application public. 1. Select the database and choose File - Replication - Settings. 2. Click Other and select Temporarily disable replication. 3. Click OK. 4. Choose File - Database - Properties and click the Design tab. 5. Deselect List in Database Catalog. 6. Deselect Show in Open Database Dialog. For more information on access control, see Controlling and monitoring access to databases in Managing Domino Databases.

Giving designers access to a database


1. Select the database and choose File - Database - Access Control. Note that if the database is on a server and not local, you must already have manager access to the database. 2. Highlight your name in the People, Servers, Groups list. 3. Select Manager as the Access level, if it is not already selected. You must do this locally; you cannot assign yourself manager access to a database on a server. 4. Select Person as the User Type. 5. Select all the Create and Delete options. 6. Highlight -Default- and select No Access as the Access level. 7. If there are other designers, click Add and select the location of their names from the drop-down list of Address Books (for example, your Personal Address Book and the Domino Directory).

Chapter 13: Restricting Access to and Securing Parts of an Application 349

8. Click the left column next to each designers name to select it, and click Add. 9. Click OK when you have added all the designers. 10. For each designers name in the People, Servers, Groups list, highlight the name, select Designer as the Access level, and select all Create and Delete options. 11. To remove an entry, highlight the name and click Remove. 12. To change an entrys access level, highlight the name and select a new access level. 13. Click OK. To preview in the Web browser, you need to set up an Anonymous user with Author access and make sure that create documents is selected. For more information on restricting access using the ACL, see Controlling and monitoring access to databases in Managing Domino Databases.

Enforcing encrypted Web transactions using SSL


The Secure Sockets Layer (SSL) is a security protocol that protects data by encrypting it as it passes between servers and Web clients. One option the server administrator may choose in setting up SSL at the server is to enable the SSL port in the Server document of the Domino Directory, create an SSL certificate, and distribute the certificate to Web users. To protect transactions in individual databases for example, in databases used for commercial transactions open the property box for the database and select Web Access: Require SSL Connection. To open SSL-protected databases, Web users must include the SSL certificate in their browser configuration. Note that the server administrator actually has three options in allowing access over the SSL port: Anonymous access over the SSL port - Web users can connect to the server using the SSL port, however, the server allows anonymous users. Name and password access: Web users connect to the server over the SSL port, and authenticate using name and password. Access through client certificates: Web users have been issued an X509 client certificate and connect to the server over the SSL port. They are authenticated using this client certificate.

350 Application Development with Domino Designer

Depending on which of these types of access the server allows for the SSL port and what the database ACL allows, the user may access this database anonymously, may be authenticated with name and password authentication, or may use a Client certificate. For more information, see Administering the Domino System.

Restricting access to documents


Domino provides a layered security model that allows you great flexibility for controlling access to all or part of an application. The highest level of security is managed through the database access control list (ACL). Using ACL settings, you can carefully control who has access to an application and specify the type of access allowed. For example, one user might have access to read, create, and edit documents in a database, while another can only read documents. You can restrict access to documents in the following ways: Create a read access list for a view or folder that restricts who can see the view or folder. Create a write access list for a folder that restricts who can update the contents of a folder. Create a form access list to specify who can create new documents using that form. This setting also restricts who can read the documents created from the form. Create Readers and Authors fields to limit access to specific documents created from a form.

Restricting who can see a view or folder


If you want some users and not others to see a view or folder, you can create a read access list. Users who are excluded from the access list will no longer see the view or folder on the View menu. A view or folder read access list is not a true security measure. Users can create private views or folders that display the documents shown in your restricted view, unless the documents are otherwise protected. For greater security, use a read access list for a form. You can add users to the read access list for a view or folder as long as they already have at least Reader access in the database access control list.

Chapter 13: Restricting Access to and Securing Parts of an Application 351

To create a read access list 1. Open the view or folder. 2. Choose Design - View Properties or Design - Folder Properties. 3. Click the Security tab. 4. Deselect All readers and above. 5. Click each user, group, server, or access role you want to include. A checkmark appears next to each selected name. 6. Click the Person icon to add person or group names from a Personal Address Book or from the Domino Directory. 7. To remove a name from the list, click the name again to remove the checkmark. 8. Check Available to Public Access Users if you want this view or folder available to users with public access read or write privileges in the access control list for this database. 9. Save the view or folder. Do not create a read access list for the default view of a database. Servers that need to replicate a database need access to views that are read-restricted so that view design changes can replicate. Example: Restricting access to a view To improve his Technical Services departments reputation, Rajeev Jain has designed a Tech Services Review form, which is included in the companys custom Mail template. Each quarter, Rajeev sends a company-wide memo asking people to complete a Tech Services Review form and mail it to a Service Request Tracking database. In that database, the reviews are displayed in the Tech Service Performance view. Rajeev wants only his technicians and his own managers to have access to this view. He defines a read access list for the Tech Service Performance view. Then, since there is no group in the Domino Directory for the people he wants to include in the access list, Rajeev defines an access role in the database ACL called [TS Managers], and adds that role to the views read access list. The access role is stored within the Service Request Tracking database; it does not get added to the Domino Directory. For more information on restricting access to a database, see Controlling and monitoring access to databases in Managing Domino Databases.

352 Application Development with Domino Designer

Restricting who can update the contents of a folder


To allow some users and not others to update the contents of a folder, create a write access list for the folder. You can add users to the a write access list for a folder as long as they already have at least Author access in the database access control list. Users specified in the write access list for the folder can move and copy documents into the folder and can remove documents from the folder. They cannot update the documents themselves. 1. Select a database. 2. In the Design pane, click Folders. 3. Double-click the view or folder in the Work pane. 4. Choose Design - Folder Properties. 5. Click the Security tab. 6. In the Contents can be updated by: section, deselect All Authors and above. 7. Click each user, group, server, or access role you want to include. A check mark appears next to each selected name. 8. Click the Person icon to add person or group names from a Personal Address Book or from the Domino Directory. 9. To remove a name from the list, click the name again to remove the check mark 10. Save the folder.

Restricting access to all documents created from a form


To restrict access to all documents created from a form, you can create a form access list. Create this list at the Security tab of the Form Properties box. The form access list lets you restrict: Who can access the form in order to create documents using the form. If users are not on this list, then when they select the Create menu, they will not see this form on the list. This is one way to shorten the list. Who can read documents created from this form. If you choose this restriction, a read access list that restricts who can read the document is created.

Chapter 13: Restricting Access to and Securing Parts of an Application 353

Restricting access in this way is not a true security measure because a user might create a copy of the form and remove the restriction, but it is a useful tool for limiting easy access. For example, you might use a form access list to restrict access to documents containing personnel information. In addition to restricting who can read or edit documents created from a form, you might want to restrict actions users can take with documents. For example, you might want to allow users to view a company phone list, but prevent them from printing, copying, or forwarding the list. Restricting access to a form Using a form access list, you restrict access to all or part of a form by setting security parameters that work with the database ACL. The database ACL predominates only users with access to the database have access to forms within a database. Form security is a lower level of access control than is the database access control list. You can create form access lists that specify who can create, edit, print, forward, or copy information. Limiting who can create documents from a form also shortens the Create menu by removing restricted forms from the menu. Authorized readers The following people can read a document that has restricted read access: Users assigned read access in the form access list Users listed in the forms Readers field Readers field names are added to a documents read access list. Users listed in the forms Authors field Creating fields for Readers and Authors is described later in this chapter. Replicating restricted documents Adding names to a read access list or to a Readers field limits access to the users, groups, and servers named in that list or field. Servers that need to replicate this database must be included in the list or field to have read access. Otherwise, documents that are read-restricted wont replicate.

Restricting who can create or read all documents from a form


1. Open the form. 2. Choose Design - Form Properties. 3. Click the Security tab. 4. Deselect All authors and above in the Who can create documents with this form section. 5. Click each user, group, server, and access role you want to include.

354 Application Development with Domino Designer

6. Deselect All readers and above in the Default read access for documents created with this form section. 7. Click each user, group, server, and access role you want to include. 8. (Optional) Check Disable printing/forwarding/copying to clipboard if you want to disable these features. 9. (Optional) Check Available to Public Access users if you want documents in this view or folder available to users with public access read or write privileges in the access control list for this database.

Preventing printing, forwarding, and copying of documents


You can discourage users from printing, forwarding, or copying documents created with a form. This feature helps to prevent accidental distribution of confidential information, but it is not a true security feature since users can circumvent it by using screen capture programs. 1. Open the form. 2. Choose Design - Form Properties. 3. Click the Security tab. 4. Click Disable printing/forwarding/copying to clipboard.

Using a Readers field to restrict access to specific documents


To limit access to specific documents created from a form, include a Readers field on the form. A Readers field explicitly lists the users who can read documents created from the form. For example, to limit access to an employees personnel file to members of the Human Resources department, the employee, and the employees manager, list those people in a Readers field. Without Reader access to a document, a user cannot see the document in a view. If a form has an access list, names from the Readers field are added to the form access list. Otherwise, the Readers field controls access to documents created from the form. Entries in a Readers field cannot give a user more access than what is specified in the database access control list (ACL); they can only further restrict access. Users who have been assigned No Access to a database can never read a document, even if you list them in a Readers field. On the other hand, users with Editor access or above in the ACL can be restricted from reading documents if they arent included in a Readers field.

Chapter 13: Restricting Access to and Securing Parts of an Application 355

Any users who have Editor (or higher) access to the database can edit a document if: They are listed in the forms read access list, Readers field, or Authors field. The form has no read access list restrictions, no Readers field, and no Authors field. For information on updating Readers fields, see Updating Reader and Author fields in Managing Domino Databases.

Using an Authors field to restrict who can edit specific documents


An Authors field works in conjunction with Author access in the database access control list (ACL). If you assign a user Author access in the ACL, the user can read documents in the database but cannot edit even their own documents. Listing users in an Authors field expands access rights by allowing the listed users to edit documents they create. Entries in an Authors field cannot override the database access control list; they can only refine it. Users who have been assigned No Access to a database can never edit a document, even if you list them in an Authors field. Users who already have Editor (or higher) access to the database are not affected by an Authors field. Authors fields affect only users who have Author access to the database. Note that the name you enter in the Authors field must be the complete hierarchical name for example, John Smith/ACME/West not the shortened common name form. For information on updating Authors fields, see Updating Reader and Author fields in Managing Domino Databases.

Restricting who can read or edit specific documents


To restrict who can read documents, add a Readers field to a form. To allow users with Author access to edit the documents they create, add an Authors field to a form. Note This type of access control only takes effect when the database is on a server. If you develop a database locally, you cant test this feature until you copy the database to a server.

356 Application Development with Domino Designer

1. Open the form. 2. Create a field, or click an existing field. Then choose Design - Field Properties. 3. At the Field Info tab, select Readers or Authors as the type. Select Editable to allow authors and editors to modify the list (Be sure to include yourself in the default value formulas which you create in the Script area of the Programmers pane so there is at least one value). Select Computed to write a formula that computes the reader or author names. 4. To create editable or computed field values, click the Programmers pane, select a formula type, and write the formula; click the green check mark to save the formula. Note Include server names in the formula if the database will replicate. 5. On the Control tab, select a Choices option other than None to generate a list of readers or authors from which users can select. 6. (Optional) On the Field Info tab, select Allow multi-values to allow more than one name to be stored in the field. 7. (Optional) On the Control tab, select Allow values not in list to let users enter additional names. This property is applicable only to Address and Access Control List choices. 8. Close and save the form. To ensure that the database will replicate correctly, include the names of replicating servers in the reader names list. Choices for generating a list of readers or authors Unless None is selected as the lookup option for a Readers or Authors field, users either press CTRL+ENTER or, if specified for the field, the entry helper button to see a list of possible entries. If the Readers field is located inside a layout region, leave None selected; other lookup options do not apply. On the Control tab of the Field Properties box, choose one of these options for generating a readers or authors list: None If you select None, you rely on a formula or on authors to create the list of names. Select Look up names as each character is entered to speed up typing in editable fields. Designer fills in the first name that matches the characters the user types.

Chapter 13: Restricting Access to and Securing Parts of an Application 357

Use Address dialog for choices This option displays the Names dialog box so users can select names from a Personal Address Book or from the Domino Directory. Select Look up names as each character is entered to help users fill in a name quickly and Designer looks up a match. Use access control list for choices This option brings up a list of people, servers, groups, and roles in the access control list. Use View dialog for choices This option brings up a dialog box containing entries from a column in a Designer database view. Select the database to look up, select a view, and select a column number. Writing formulas for Readers and Authors fields When you write a formula for a Readers or Authors field, enclose user names and group names in quotation marks.
Marketing"

Select Allow multi-values for a field that stores a text list with multiple names. Concatenate the names in the formula with a colon.
"Mary Sen":"Marketing":"Joyce O'Connor"

Role names that qualify access levels are surrounded by quotation marks and square brackets.
"[Scheduling Committee]"

Examples: Restricting who can read or edit specific documents Adding a Readers field to a form You want to be sure that employees can read only their own Employee Information documents. Create a computed-when-composed Readers field named AuthorizedReader that uses this formula:
@UserName

To add additional authorized readers, create a read access list in the Document Properties box for individual documents.

358 Application Development with Domino Designer

Adding an Authors field to a form You want to use an Authors field on a Slide Show form to let the Production group edit documents, but you also want to save and display the original authors name for each document, so the creators name is easily found even after the document is edited. You create two fields. To display the creators name, create a computed-when-composed field called CreatedBy with the formula:
@Name([CN];@UserName)

To allow the Production group to edit Slide Show documents, create a computed Authors field and use the formula:
"Production"

Allowing authors to add other names You want to let authors and editors customize the Authors list. Create an editable Authors field that uses View access control list dialog to present choices, and select Allow multi-values for the field.

Tracking who edits a document


If a document contains an Authors field, Designer automatically stores the names of the users who have edited that document in an internal field called $UpdatedBy. Servers involved in replication are not considered editors, so theyre not tracked in this list. To display the contents of the $UpdatedBy field, users can click and hold the Authors field in a document theyre reading. Designer displays a pop-up showing the names of everyone who has modified the document, including people who did so through agents. Adding pop-up text to the field label helps users understand the list. Designer displays hierarchical user names in abbreviated form: Betty Powers/R&D/WorkSavers/US If Anonymous form was selected for the form, documents do not contain an $UpdatedBy field, but have an $Anonymous field with a value of 1 instead.

Chapter 13: Restricting Access to and Securing Parts of an Application 359

Restricting authors from changing fields in existing documents


You can prevent users with Author access in the database ACL from editing a field in existing documents. This restriction doesnt apply to new documents. 1. Open the form. 2. Create a field, or click an existing field. 3. In the Field Properties box, click the Advanced tab. 4. Select Security options: Must have at least Editor access to use and click the check mark.

Creating pages, forms, outlines, views, and agents for public access
A public access list, like Readers and Authors fields, works with the database access control list to control users access to specific design elements. Users with No Access or Depositor access in the ACL cannot access the design elements of a database. To give them the ability to view specific pages, documents, forms, outlines, views, and folders make the design element available to pubic access users. Users who have at least Reader access in the database ACL will see in the elements properties box that the element has been designated as available for public access. To create public documents, you must create a public access form with a $PublicAccess field and create a public folder or view to display the documents. Public documents are useful for calendar applications where one user might delegate to another user the ability to read or create appointments on his or her behalf. Creating agents enabled for public access gives users with No Access or Depositor the ability to view and use any manually run agents. For more information on the ACL, see Controlling and monitoring access to databases in Managing Domino Databases. To create a page or form for public access 1. Open the page or form. 2. Choose Design - <design element> Properties. 3. Click the Security tab. 4. Select Available to Public Access Users. 5. On a form, create a field. 6. In the Name field, enter $PublicAccess. 7. In the Type field, select Text and Computed when composed.
360 Application Development with Domino Designer

8. In the Programmers pane at the bottom of the form, enter 1 as the default value for the field. Click the green check mark to accept the value. 9. To hide this field from users, select the Hide When tab and specify hide-when conditions. To create a view for public access 1. Open the view. 2. Choose Design - View Properties. 3. Click the Security tab. 4. Check Available to public access users if you want documents in this view or folder available to users with public access read or write privileges in the access control list for this database. To create an outline for public access 1. Open the outline 2. Choose Design - Outline Properties. 3. Check Available to public access users. To create an agent for Public Access 1. Open the agent in Designer. 2. Click Options. 3. Select Available to Public Access Users.

Encrypting documents in Notes applications


Encrypted documents contain one or more encrypted fields that are linked to keys that encrypt the field data. For example, documents created with the Notes mail template are encrypted. The encryption process occurs automatically (through the form design) or manually by authors and editors. Associating multiple encryption keys with a document automatically encrypts all encryptable fields with the same keys. You cannot link a particular key to a particular field. Encryption keys can be secret that is, keys that you must send to users in order for them to decrypt a field or public that is, keys that are already associated with a users Person document in the Domino Directory. Public keys are used for encrypting mail documents. Caution Web users can see encrypted fields. Do not rely on encrypted fields as a way to restrict access for Web users.

Chapter 13: Restricting Access to and Securing Parts of an Application 361

Reading encrypted information


Users can read encrypted information if they have the correct encryption key in their Notes User ID or in their Person document in the Domino Directory. Users without the correct encryption key can read unencrypted parts of a document, but encrypted fields appear blank. When multiple keys are associated with a form or document, users need only one of the specified keys to read encrypted information.

Editing and saving encrypted information


Users who dont have the correct encryption key in their Notes User ID cant edit encrypted documents. They can create new documents but must save them unencrypted by removing the encryption key from the Document Properties box. When multiple secret keys are associated with a form or document, users need all of the specified keys to edit and save encrypted information with the original keys. If they dont have all the necessary keys, they can still encrypt documents with the keys they have by changing the encryption key list in the Document Properties box.

Removing or changing encryption keys for a document


Authors can remove encryption or change the associated keys from their own documents (if they are allowed to edit their documents and they have all associated encryption keys). Editors can remove encryption from and change the keys associated with any document.

Data security for encrypted information


If a user copies the database, the data remains encrypted even if the database is copied at the operating system level. The encrypted data is also safe from access by API programs. Caution Full text searches that include the option Index encrypted fields will show encrypted data to any users who have access to the database. Also, if a user who has the power to decrypt documents creates the index, that user can read the full text index as an ASCII text file at the server.

362 Application Development with Domino Designer

Encrypting documents
To use encryption in a document, you create fields that are capable of being encrypted and then you or users encrypt the fields with one or more encryption keys. To encrypt a document, perform some or all of these steps: 1. (Optional) Create an encryption key to use secret encryption. To do this, see the topic Creating a secret encryption key. 2. Enable encryption for a field. A document cannot be encrypted unless it contains at least one field that has been designated as encryptable. 3. Choose a method for assigning encryption keys to documents: Encrypt all documents automatically Create a field that generates a list of encryption keys Allow authors to encrypt documents with their own encryption keys A document can be encrypted when it is first saved, or it can be encrypted when saved after a subsequent editing session. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases. Example: how decrypting a document works Mary encrypts a document using the encryption key in her User ID to encrypt field data. David opens the encrypted document to read it. Designer compares the list of encryption keys used to encrypt the document with the encryption keys in Davids User ID. If David doesnt have any of the same keys, the encrypted fields appear to be blank. If David has some of the keys used to encrypt the document, that encryption key is used to decrypt the document. Examples: Making fields for encrypting documents For an Employee Information database, the Salary History form has a create access list that allows only members of the Financials group to create Salary History documents. The database managers want to allow only four people in the Financials group to see salary information and to edit Salary History documents. The database manager can create an encryption key and distribute it to the select group or identify the four people and encrypt the information using their public encryption keys.

Chapter 13: Restricting Access to and Securing Parts of an Application 363

In the first instance, the database manager creates an encryption key called Salary and sends it to the four people in the Financials group, and to the database designer. The database designer enables encryption for the CurrentSalary field and associates the Salary encryption key with the form. This allows the four people in the Financials group who have the Salary encryption key to create, read, and edit encrypted salary history documents, including the data in the CurrentSalary field. In the second case, the manager provides the names of the four people to the database designer, who chooses their names from the Public Encryption key list associated with the CurrentSalary field. Then the people from named in the list can create, read, and edit encrypted salary history documents, including the data in the CurrentSalary field. Users who dont have the Salary encryption key and are not in the Public Key list can read everything in the salary history documents, except the data in the CurrentSalary field, but they cant edit and save existing encrypted documents.

Creating a secret encryption key


Database managers create and distribute secret encryption keys to users who need to decrypt documents that are encrypted with the secret keys. None of this is necessary if you use public keys for encryption. 1. Choose File - Tools - User ID. 2. Click the Encryption icon. 3. Click New. 4. Enter a name that describes the purpose of the new key. 5. Click North American only if the key is to be used in the U.S. and Canada; click International if the key is to be used in additional countries. 6. (Optional) Write a comment to explain the keys use for example, the databases to use it with, the people who have copies of it, and so on. 7. Click OK, then click Done. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases. Encryption keys and private keys in Notes IDs Every Notes User ID has a public key and private key that encrypt mail, fields, and documents and verify a writers identity. A User ID may also contain additional encryption keys that encrypt and decrypt documents.

364 Application Development with Domino Designer

When you design a form, you can use the public key for encryption or create a new encryption key. If you create a new encryption key, Designer automatically stores it in your User ID. If someone sends you an encryption key, Designer stores the new key in your User ID, along with any other keys. North American and International encryption keys Designer uses two schemes for creating encryption keys. One scheme is for North American (United States and Canada) use only, and the other is for use anywhere in the world. If you are designing a database for users in the United States and Canada and in other countries, create domestic and international versions of the encryption key. If a document is encrypted with a North American encryption key, people using Designer outside of the United States and Canada cannot decrypt the document because they cant add a North American encryption key to their international IDs. Because of legal restrictions, you cannot mail an encryption key with the North American encryption scheme outside the United States and Canada. When American and Canadian users receive keys encrypted with the international scheme, they cannot change the key to the North American encryption scheme. Enabling encryption for a field You can enable encryption of a field whenever the document containing the field is saved. Forms can contain more than one encryption-enabled field. 1. Open the form. 2. Create a field or click an existing field. Then choose Design - Field Properties. The field can be any data type. 3. Click the Advanced tab. 4. Select Security options: Enable encryption for this field.

Encrypting documents automatically


You can encrypt all encryptable fields automatically whenever someone saves a new document composed with a form. 1. Open the form. 2. Choose Design - Form Properties. 3. Click the Security tab. 4. The Default encryption keys list shows all secret encryption keys in your ID. Click the ones you want to add to the form as defaults. 5. Close and save the form.
Chapter 13: Restricting Access to and Securing Parts of an Application 365

To encrypt all documents created with a form, you enable encryption for one or more of the forms fields (in the Field Properties box) and assign one or more existing encryption keys to the form (in the Form Properties box). If you use secret rather than public encryption keys, the database manager is in charge of distributing the encryption keys to all users who need them. Whenever someone saves a new document composed with that form, all the encryptable fields in that document are encrypted using the key(s) you assigned, unless the author or editor changes the encryption keys associated with the document or disables encryption. Documents created before you add the encryption keys remain unencrypted; however, you can manually encrypt them. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases.

Creating a field that generates a list of secret encryption keys


If you are using secret encryption keys rather than public encryption keys to encrypt documents, maintain a list of the keys you create. To provide a convenient list of frequently used encryption keys, create a special SecretEncryptionKeys field. To create this special field, the form must already have fields enabled for encryption. 1. Open the form. 2. Create a field named SecretEncryptionKey. Define it as a text or list choice field that is editable or computed. 3. For a list choice field, click the Control tab and select Enter choices (one per line). Write each entry, using a keyword and a synonym that describes the encryption key for example, Encrypt | ConfidentialKey. Use a null value for the Dont encrypt option. 4. Click the Programmers pane and choose Formula in the Script area. 5. For a computed field, add a formula that returns the name of the encryption key to use; for an editable field, add a default value formula. 6. (Optional) Click the Advanced tab. Select Security options: Enable encryption for this field so unauthorized users cannot see the names of encryption keys used in the formulas and keywords. 7. Close and save the form. Users must have a copy of the encryption key so that they can save documents. The database manager is in charge of distributing secret encryption keys to all users who need them.

366 Application Development with Domino Designer

If the SecretEncryptionKeys field is empty (null), the document is not encrypted. For more information on encryption, see Encrypting databases and distributing encryption keys in Managing Domino Databases. Examples: Creating a field that generates a list of encryption keys Editable choice list field that lists one key This example gives users two choices. If the user selects Encrypt, the document is encrypted with the ConfidentialKey encryption key. If the user selects Dont encrypt (represented by a null value ), the document is not encrypted.
Encrypt | ConfidentialKey Don't encrypt | ""

Editable choice list field that lists multiple keys A choice list formula lets users choose the encryption key that is appropriate for the document.
Encrypt for Financials group | FinancialsKey Encrypt for Managers group | ManagersKey Encrypt for Human Resources group | HRKey Don't encrypt | ""

Editable text field You can create a SecretEncryptionKeys field that is an editable text field with a default value formula that designates a commonly used key. Users can remove the value to skip encryption or change the value to use another key.
"ConfidentialKey"

Computed text field This formula encrypts documents with the ConfidentialKey encryption key if the Status field contains the word Confidential:
@If(Status="Confidential";"ConfidentialKey";"");

Allowing the author to choose the encryption key If you dont have access to the encryption key or you want authors to choose from the encryption keys they possess, enable encryption for the fields, but do not associate any encryption keys with the form. Then when users save a document created with the form, they choose whether to encrypt the document when saving it (in the Document Properties box) and choose which encryption key to use.

Chapter 13: Restricting Access to and Securing Parts of an Application 367

Restricting who can edit a section


In workflow applications, use sections to restrict who can edit or sign parts of a document. If a document requires more than one approval signature, you create a section on the form for each signature or group. For example, you might create a section specifically for the Purchasing group.

Edit access lists and the access control list


The edit access list for a section cannot override the database access control list; it can only refine it. A user must already have at least Editor access to the database in order to edit a document. Privilege names cannot be used in the edit access list. If you use custom roles to refine standard access levels, it is often helpful to create a section that corresponds to each access role. You can reveal the role at the top of the section with the RoleName field that is tracking it. If you have document buttons relevant to particular roles, place them next to each roles section.

Using a computed field to define section editors


To define a list of section editors, write a formula that populates the list of allowed editors, either by including the current users name, by using @DbColumn to retrieve a list of names, using the value of an approver field, or using a group name or role from the access control list. Use a computed-when-composed section to create a permanent list of editors when a document is created. You can use only formulas that result in a text list containing one or more names; these names are added to the sections edit access list. Enclose the names in quotation marks and concatenate them with a colon ( : ). Mary Sen:Marketing Group Access role names must include their square brackets and be enclosed in quotation marks: [Scheduling Committee] For information on using @DbColumn, see the Programming Guide.

368 Application Development with Domino Designer

Allowing the author to name section editors


To let authors decide who can edit fields in a section, make the section editable. As a convenience to authors, write a default value formula to create an initial list of editors for the section; anyone editing the section can then update that list. If there are multiple authors, be sure to select Allow multi-values for the field. An editable section allows each documents author to create a customized list of editors by double-clicking the section title when the document is in Edit mode or choosing Section - Define Editors. Any users already authorized to edit the fields within the section are displayed, and the author can add other editors to the list.

Using an access-controlled section on multiple forms.


To use an access-controlled section on more than one form, place the section on a subform and include the subform in the forms. An access-controlled section can be used in several forms by placing it on a subform.

Restricting who can access a section of a document


To create an access-controlled section 1. Highlight the text, fields, and other design elements on a form that make up the section. 2. Choose Create - Section - Controlled Access. 3. (Optional) In the Section Properties box, edit the section title. 4. (Optional) Enter a Section Field Name. 5. (Optional) Choose a border style and border color for the section. You can insert fields and other design elements into the section after creating it. To append design elements to the bottom of the section, you must recreate the section. To name the editors for an access-controlled section 1. Click the section title. 2. Choose Section - Section Properties. 3. Click the Formula tab. 4. Select Editable as the section type to allow the document creator to specify the section editors.
Chapter 13: Restricting Access to and Securing Parts of an Application 369

5. Select one of the Computed types to use a formula to define the section editors. 6. (Optional for an editable field; Required for a computed field) In the Properties box, write a formula to define who can edit the field and click the green check mark. To collapse an access-controlled section 1. Click the section marker and choose Section - Section Properties. 2. Click the Expand/Collapse tab and select options for showing the section expanded or collapsed, depending on whether a document is being previewed, printed, or opened. 3. On the same tab, click the For Editors drop-down list and select For Non-editors. A list of options appears for displaying the section to users who can read but not edit the section. 4. Select Hide title when expanded if users dont need to see the section title when the fields are displayed. 5. Close and save the form. Examples: Restricting access to a section Computing an editors list from the access control list The status section of a Business Card Request form has an access-controlled section whose formula allows only administrators (an access role in the access control list) to change the status of a request. The formula for the computed field is:
"[Business Card Administrators]"

Allowing the author to name section editors An editable section of a Status Report form has an access-controlled section whose default value formula always allows the author to edit the status report.
"@UserName"

The author can choose Section - Define Editors to name additional editors for a particular status report.

370 Application Development with Domino Designer

Attaching electronic signatures to documents and sections in Notes applications


For extra security, you can have Designer attach electronic signatures to documents. Electronic signatures assure a reader that the writers identity is genuine and that information has not changed since the writer mailed or saved the document. Note Signatures are valid only in Notes applications; they are not supported on the Web. To design a form whose documents can be signed, you create at least one field to which you assign the property Sign if mailed or saved in section. This feature is available only for forms that are mail-enabled and for forms that contain access-controlled sections. You can enable signing of one or more fields on a form. If the field is in an access-controlled section, the signature applies only to the section and is generated when the document is saved. If the field is not in an access-controlled section, the signature is generated only when the document is mailed. To generate multiple signatures on a form, create multiple sign-enabled fields, placed in separate access-controlled sections.

Attaching signatures to documents


To attach a signature to a document during mailing: The form must contain a SendTo field or, as an alternative, you can create a LotusScript program that uses the Send method of the NotesDocument class with a recipients argument. The form must have at least one sign-enabled field. To sign-enable a field, assign the property Sign if mailed or saved in section in the Control tab of the Field Properties box. The form enables mailing by using one of the following: a Send Document form action, the form property On Close: Present mail send dialog, a MailOptions field with the value 1, an @MailSend formula, or a LotusScript program that uses the Send method of the NotesDocument or NotesUIDocument class. The signing occurs during mailing in one of the following ways: the sender chooses Sign in the Mail Send dialog box, the form contains a field named Sign with the value 1, the form uses @MailSend with the [Sign] flag, or the form uses a LotusScript program with the SignOnSend property set to TRUE.

Chapter 13: Restricting Access to and Securing Parts of an Application 371

Attaching signatures to access-controlled sections


To attach a signature to a document when it is saved: The form must contain an access-controlled section. The access-controlled section must have at least one sign-enabled field. To sign-enable a form, assign the property Sign if mailed or saved in section is selected in the Control tab of the Field Properties box.

How Designer stores and verifies electronic signatures in Notes applications


Designer combines the data in a sign-enabled field with the private key from the senders User ID to create a unique electronic signature. Designer stores the signature, along with the public key and the list of certificates from the senders ID, in the document. Note Signatures are valid only in Notes applications; they are not supported on the Web.

Storing signatures in documents


Designer stores signatures in mailed documents with the document. If a user with Editor access in the database ACL changes a field in a document, Notes replaces the existing signature with the signature of the editor when the document is mailed. Notes cannot save more than one mail-time signature for a document. If the document contains several sign-enabled fields, Designer uses data from each sign-enabled field to generate a signature. After mailing, a change in any field causes verification to fail when the recipient opens the document.

Storing signatures in sections


For documents with one sign-enabled, access-controlled section, Designer stores the signature with the section. If a user with Editor access in the database ACL changes a sign-enabled section, Designer replaces the existing signature with the editors signature when the document is resaved. If there are several sign-enabled fields in the section, Designer uses data from each sign-enabled field in the section to generate a signature. After saving, a change to a field in the document causes verification to fail when a reader opens the document.

372 Application Development with Domino Designer

For documents with several sign-enabled, access-controlled sections, Designer stores signatures within each section, so it is possible to maintain multiple signatures for a document. If a user with editor access changes one or more sign-enabled sections, Designer replaces all original section signatures with the newer signature when resaving the document. Designer preserves the existing signatures for sections for which the user has no access. If there are several sign-enabled fields within a section, data from all the sign-enabled fields in that section is used to generate a signature. A change in any fields in the document after saving causes verification to fail when a reader opens the document.

Example: Verifying signatures


1. Mary mails or saves a sign-enabled document. Notes uses the private key from Marys User ID and the sign-enabled field data to create a unique signature. Designer also stores Marys public key and certificates with the document. 2. David opens the signed document to read it. 3. Notes checks to see if the document was signed. If it was, Designer checks the signature against the data to see if it matches. 4. Notes checks the certificates that came from Marys ID against Davids ID to see if they share a common certifier or cross-certificate in the ID. 5. One of the following occurs: If the signature and data are verified, Notes displays a message indicating who signed it. If the data has been modified, Notes displays a message indicating that the document has been changed or corrupted since Mary saved it. David should not assume that the content of the document is what Mary created. If the signature cant be verified or David and Mary dont share a common certificate, Notes displays a message that the signature cant be verified. David should not assume that Mary created the document. For more information on certification, see Administering the Domino System.

Chapter 13: Restricting Access to and Securing Parts of an Application 373

Chapter 14 Completing an Application and Managing Design Changes


This chapter describes how to document an application and how to test it before deployment. Because applications often require redesign, this chapter also describes how to make, control, and distribute design changes to applications that are already in use.

Completing an application
As you prepare to deploy an application, consider these finishing touches: Creating an icon for the application. Creating database help using the standard About this Database and Using this Database pages, or with a designated home page that describes the application or site. You may also want to: Provide context-sensitive help for an application Provide customized SmartIcons sets for a Notes application, to give users one-click buttons for frequent tasks Then, before handing over the application to the database manager: Test the design Make a master design copy to manage future design changes For more information on putting a database into production, see Managing Domino Databases.

Creating a database icon for a Notes application


A database icon helps users identify the database quickly on their Bookmark pane. An icon visually represents the purpose of the database. For example, a problem-reporting database for a software development group might display an insect icon to represent the bugs that users report. A discussion database where users ask questions about new products could include an icon with a question mark.
375

Creating a database icon


You can create a database icon by copying an icon from another database and pasting it in, by pasting a bitmap from a graphics application, or by creating an icon in Designer. To paste an icon into a database 1. Copy an icon from another database or copy a graphic from a graphics application to the clipboard. If you are copying a bitmap, reduce the bitmap size to a 1/2-inch square (32 x 32 pixels). You cannot resize it in Designer, and Designer truncates larger bitmaps. 2. Copy the bitmap to the Clipboard. 3. In Designer, open the database in which you want to paste the icon. 4. In the Design pane, click Resources - Other. 5. Double-click Icon to start the Icon editor. 6. Click Paste. 7. While still in the icon editor, you can make changes to the icon. To create a new icon You must have a mouse to create a new icon. 1. Open a database in Designer. 2. In the Design pane, click Resources - Other. 3. Double-click Icon. 4. Click a color and click a square to fill it with the chosen color. 5. Continue filling in blocks until the icon is complete. 6. Click OK to save the icon. Note Icon changes do not replicate and are not affected by replace or refresh design procedures. To distribute icon changes, copy the icon to each database. The icon design will refresh or replace if you disable Prohibit design refresh or replace to modify on the Design tab of the Design Document Properties box (To get this Properties box, select Icon in the Work pane and then select File - Document Properties).

376 Application Development with Domino Designer

Providing online help for an application


Including help with your application improves the chances that users will understand how to use it without asking for individual help from you or a co-worker. Database help can be integrated throughout the application so that users have information as they need it. Use these tools and techniques to document an application: About This Database and Using This Database documents describe the database purpose. You can also create a page that provides this type of information. The document preview pane helps users scan through documents quickly to get a sense of whats in the database. Database launch settings allow you to display the most useful starting point for users. This might be the About This Database page or it might be the home page for the application. Context-sensitive help in applications lets you write application-specific help that users access with a Help button or the F1 key in a Notes application or with a Help button in a Web application. Field help describes the purpose and use of individual fields. A help view organizes and displays help documents. A separate Help database can be set to stay on top of other windows in your application while users work.

Creating About and Using documents for a database


Every database should include an About This Database document and a Using This Database document to explain the database to users. The About This Database document Use an About This Database document to describe the purpose of a database. You can specify that the About document opens automatically when a user opens the database. To display this document, choose Help About This Database. The About document should include: The purpose of the database. The intended audience. The name and telephone number of the database manager.

Chapter 14: Completing an Application and Managing Design Changes 377

The date the database was implemented. Guidelines for its use. Network requirements if users must be connected to the network to perform certain tasks for example, if the application uses lookups that require a network connection. The About document can contain rich text, so you can also use document, view, and database links, buttons, attachments, graphics, or multimedia files. The Using This Database document Create a Using This Database document to provide users with instructions on using various forms, views, and navigators in the database. To display this document, users choose Help - Using This Database. The Using document, like the About document, can contain rich text, so you can also add document or database links, buttons, attachments, graphics, or multimedia files. A Using This Database document should include: A quick overview of the application. The purpose of each view and its organizations. The purpose of each form and how to fill it out. The purpose of each agent, when to run it, and the anticipated results. The overall work process being automated if the application automates workflow, including what happens at each stage. When users fill out documents, they should understand what happens after the documents are saved, and what other users are expected to do. To create an About or Using document 1. In Designer, open the database youre designing. 2. In the Design pane, click Resources - Other. 3. Double-click About Database Document or Using Database Document. 4. Write or edit the information. You can also create links, buttons, hotspots, and attachments. You can apply text styles, as you would for any Notes form. 5. Save the document.

378 Application Development with Domino Designer

To automatically display the About This Database document 1. Choose File - Database - Properties and click the Launch tab. 2. Do any of the following: Select On Database Open: Open About database document to always open the About document first. Select Show About database document if modified if you edit the About document and want to show it to users again. Select Show About database document when database is opened for first time. Select On Web Open: Open About database document. You can use the About document as a springboard to a file in another database or another products file. To do so, use the Database Properties Launch options for Launch first attachment in About database document or Launch first doclink in About database document. To view the About or Using documents Do one of the following: Choose File - Database - Open, highlight a database title, and select About. This displays the About document. Open a database on the Bookmark pane and choose Help - About This Database or Using This Database.

Creating context-sensitive help for an application


In addition to writing help documents or pages for an application, you can make the documents or pages context-sensitive so that users can open them by pressing a help key such as F1 or by clicking a help button. You can associate a help document or page with each page, form, subform, view, and folder in an application. When you provide help for an element, your formula overrides whatever context-sensitive Help already exists for that element. This feature is not intended for context-sensitive help on dialog boxes or menu items. To create context-sensitive help for a Notes application, you write a formula for the onHelpRequest event for a page, form, subform, view, or folder. In the formula, you can use the formula language command @Command([OpenHelpDocument]) to specify a help document to open when the user request Help while that element is active. You can also use @Command([OpenPage]) to open a page instead of a document. The onHelpRequest event is not available when serving an application over a Web server, but you can create a button for an element and program the button using a formula with @Command([OpenHelpDocument]) or
Chapter 14: Completing an Application and Managing Design Changes 379

@Command([OpenPage]). A user clicks the Help button to see the associated help document or page. Because the onHelpRequest event accepts a formula, you can use the formula language in other ways to provide help. For example, you can use an @If formula with @IsDocBeingEdited to provide different help for a form depending on whether a document is being read or edited, or depending on other conditions specific to your application. You can present a dialog box to allow users to select among several help documents or pages. You can place help text directly onto a form or page, set the text with a hide-when formula, and use a formula on the onHelpRequest event to reveal the text (by changing the value of a document field) when a user requests help. Tip To open documents in response to help requests, there must be a view containing those documents sorted by a key field that you can use as parameters for @Command([OpenHelpDocument]). You can use @Command([OpenPage]) without requiring a specific view or key field. For syntax and usage information on using @Command([OpenHelp Document]) or @Command([OpenPage]) in a formula, see the Programming Guide.

Writing help for fields


Field help is optional, but it can help users fill out documents without assistance. A field label that appears next to the field describes the fields general purpose. Write field help to tell users what to enter in an editable field or how to use the field. When a user selects a field that has help, the one-line help-text prompt appears at the bottom of the window. If you cannot fit all the information into a help description or if the field isnt editable, but you want to explain its use, use a pop-up annotation to the field label to place help information directly on the form. Tips for writing help for fields Start the help description with Required: if the user must fill in the field. You can use 70 characters, including letters, numbers, spaces, and punctuation. If your application will be translated to another language, use no more than 55 characters to allow the translators a few extra characters. To write field help 1. Open the form or subform in Designer. 2. Double-click the field. 3. In the Field Properties box, click the Advanced tab. 4. Write a help description. 5. Close and save the form or subform.
380 Application Development with Domino Designer

To write pop-up text for a field 1. Open the form in Designer. 2. Highlight the field label that is, static text that the user sees, not the rectangular field definition. 3. Choose Create - Hotspot - Text Pop-up. 4. In the Hotspot Properties box, write the pop-up text and click the green check mark. 5. Close and save the form or subform. Examples For a text field named Supervisor:
Enter the name of the person to whom you report.

For a keywords field that presents check boxes:


Select as many options as apply.

For a required Subject field:


Required: You must add a brief description.

Creating and displaying more detailed application help


In a complex application, an About This Database document and a Using This Database document might not provide enough documentation. To provide detailed documentation for an application, design a help form as part of the database and display documents created with that form in a help view. The following steps describe one way to achieve this. To create a help form 1. Create a new form called help and create fields for help content. 2. Click the Programmers pane and select Define and the name of the form youre designing. 3. Select Event: Window Title and enter Help as the window title text in the formula window below. 4. Close and save the form. 5. Choose Create - Help to write, save, and close each help document. 6. Click the form youre designing and choose Design - Form Properties. 7. Deselect Include in Menu. 8. Click the form, and then save it. 9. Create a view that displays the help documents. Note You can also create a separate Help database and open its documents from your application using @Command(OpenHelpDocument). To open
Chapter 14: Completing an Application and Managing Design Changes 381

documents from a Help database in a window that users can set to stay on top of other windows as they work, choose File - Database - Properties Design for your database. Then, turn on List in Database Catalog and enter the category NotesHelp.

Specifying the Web site home page in the Server document


To make a design element the site home page, edit the Home URL field in the Server document or a Virtual Server document and specify a URL that includes the design element. If you set an About This Database document, a navigator, a page, or another document to launch automatically when a user opens the database, the Home URL need only open the database to launch the design element. The syntax is: /databasename.nsf This URL opens the Our Home database and displays whatever is selected in the On Web Open launch setting:
/ourhome.nsf

To open a navigator automatically, include the navigator name in the URL. The syntax is: /databasename.nsf/navigatorname This URL opens the Main Navigator in the Our Home database:
/ourhome.nsf/Main+Navigator

To open a view automatically, include the view name in the Home URL. The syntax is: /databasename.nsf/viewname This URL launches the Contents view of the Our Home database:
/ourhome.nsf/Contents

382 Application Development with Domino Designer

Restricting design changes


Once an application is complete and available, you decide how to protect the design from changes. An application can have a totally open design, where users can update forms and views and pass along design changes. An application can have a totally closed design, where users use the application as is and have no access to design elements. Designer lets you control the entire design of a database, as well as individual design elements. You can restrict changes by not allowing changes to overwrite one or all design elements, or you can hide one or all design elements from users. In almost every case, you start by making a master design copy of the application. For additional information, see the topic, Hiding the design of an application.

Checking the application design before rollout


After you complete the design, test the application and correct problems before you release it. Check the design of forms Check the design of fields Check the design of views Distribute the application for a final review Pilot-test the application Make design changes before rollout Request application sign-off For more information on putting a database into production, see Managing Domino Databases.

Chapter 14: Completing an Application and Managing Design Changes 383

Checking form design


For each form, create two or three documents and enter a variety of information into the fields. Then use this checklist to verify that the form is working as intended. Is there a default form for the database? If not, double-click the form that should be the default and choose Design - Form Properties. Click the Form Info tab and select Default database form. Do all forms appear correctly on the Create menu? Are the appropriate keyboard shortcuts used? Do the forms appear in the correct order? If not, check the names and the Include in Menu properties for the forms. Do the window titles for forms display appropriately under different conditions? If not, edit the window title formula. To display the window title when a form is printed, click the Printing tab in the Form Properties box and add &W to the formula for the header or footer. Check cross-platform compatibility: Are all fonts used in this form available (or approximated) on all platforms? Does all text display legibly? Did you use platform-specific terms where appropriate? Make your application layout as generic as possible to suit all platforms. Are related fields for example, Name and Address fields grouped together on the form? If not, move the fields and their related static text to a more suitable position. Do forms that are longer than one page have page numbers? If not, click the Printing tab in the Form Properties box and add &P to the formula for the header or footer. Do the forms include Names fields where appropriate for tracking document authors and editors? If not, add a Names field to the form.

384 Application Development with Domino Designer

Has a read-access list been defined for the form? If one is needed, define a read access list by assigning names to a Read access control list on the Security tab of the Form Properties box. Has a create access list been defined for the form? If one is needed, define a create access list by assigning names to a Compose access control list on the Security tab in the Form Properties box.

Checking field design


Are fields (including keywords fields) showing the correct information when first displayed? If not, check the default value formula. Does every editable field have a help description? If not, add help descriptions for those fields. Ensure that field descriptions are consistently worded for example, all are full sentences or all express commands and that ending punctuation for example, periods is consistent for each. Can users enter information in editable fields? If not, check the field definition. You may have selected the Computed option when defining the field. Are editable fields formatted correctly once the document is saved? If not, check the input translation formula and the format for the field. Are editable fields accepting invalid data or not accepting valid data? If so, check the input validation formula. Are computed fields computing correctly? Are they returning values of the appropriate data type? If not, check the field formula. The formula may need to include some data type conversion such as @TextToNumber. Do inherited fields inherit their data correctly? If not, check the fields default value formula. Do required fields have input validation formulas that display an appropriate message when the user tries to save the document without filling in the fields? If not, create the input validation formulas and include an explanatory message for the user.

Chapter 14: Completing an Application and Managing Design Changes 385

In time-date fields, is the time displaying correctly? If not, make sure you selected the appropriate time zone option in the Field Properties box. Are fields aligned properly with a variety of window sizes and on different monitors? If not, check the tab settings for the form. Are encrypted fields accessible to users who have the encryption key and inaccessible to all other users? Make sure that only authorized users have the encryption key. If unauthorized users have the encryption key, change the encryption key and redistribute it only to authorized users.

Checking view design


Once the database is complete, make sure the design is working. For testing purposes create a view that uses @SELECTALL to select all documents. Follow these guidelines to check view design. Is there a default view for the database? If not, double-click the view that should be the default and choose Design - View Properties. Click the Options tab and select Default view when database is first opened. Is there a view that is displayed by date? If not, add a view that sorts documents by date, so users can view documents in chronological order. Do all views appear correctly on the View menu? Are the appropriate keyboard shortcuts used? Do the views appear in the correct order? If not, check the names and the Show in View Menu selection in the View Properties box. Is the information in the view easy to read? If the view appears cluttered or the columns are too close together, reset the column width and justification. Are all the documents that should be in the view displayed, or are too many documents displayed? If the view is not displaying the correct documents, check the view selection formula.

386 Application Development with Domino Designer

Are response documents indented? If not and you want to indent responses, select Show response documents in a hierarchy on the Options tab of the View Properties box and create a column for responses. Do response documents correspond to the correct main documents? If not, check the view selection formula; also be sure that the responses-only column is placed directly to the left of the column that displays the main document information. If the view uses categories, do the categories appear correctly? If not, create a sorted, categorized column and use the name of the appropriate keywords field as its formula. If the form uses a formula, do selected documents use the correct form? If not, check the form formula. Check cross-platform compatibility. Are all fonts used in this view available (or approximated) on all platforms? Are column widths sufficient for all platforms? Did you use platform-specific terms where appropriate? Make the application layout as generic as possible to suit all platforms. If needed, does the view have a read access list? To create a read access list, select the Security tab in the View Properties box. Checking columns Is the information in each column correct? If not, check the formulas in the column definitions. Is the column returning values of the appropriate data type? If not, check the field formula. Columns display only simple text; therefore, you may need to use @TEXT in the formula to display values from numbers or time fields. Is each column displaying all the information that is contained in it? If not, you may need to adjust the column width and/or the font used to display the column. If you are using a date format in a column, have you accommodated 4-digit years so that you avoid problems with the year 2000 and beyond.

Chapter 14: Completing an Application and Managing Design Changes 387

Are the contents of columns aligned properly? For example, numbers should be right-justified; text should be left-justified or centered. Check the justification for each column. Are documents in the right order? If not, make sure that you sort on the correct columns, and that you chose the correct sort order (ascending or descending). Are documents supposed to be numbered? If so, create a new view that has a column in the left-most position that sorts in ascending order and uses @DocNumber for its formula.

Making a design copy of a completed application


Before delivering the database to the database manager for general release, make a local template copy as the design. You can make future design changes to the template and then transfer them to the server database. 1. Select the database and choose File - Database - New Copy. 2. Select Local. 3. Enter a title for the template. 4. Press TAB and change the file name to include the .NTF extension reserved for templates. 5. Select Database design only in the Copy section of the dialog box. 6. Deselect Access Control List. 7. (Optional) Click Encryption to encrypt the database and protect its contents from being accessed at the operating system level. Then click OK. 8. Choose File - Database - Access Control to define an appropriate access control list for the template. Details If you specify a directory in addition to a file name, the new database is placed in the directory you name as a subdirectory of the Notes Data directory. You specify a location for the Data directory during installation. If the directory doesnt exist, Notes creates it for you.

388 Application Development with Domino Designer

The following access levels are recommended for the access control list of a template used for design maintenance:
Default Local Domain Servers Other Domain Servers Your User Name Database Manager [Anonymous] [Default] [LocalDomainServers] [OtherDomainServers] Reader Reader No Access Manager Manager No Access or whatever the actual database should have No Access or whatever the actual database should have Manager or whatever the actual database should have No Access or whatever the actual database should have

The items within the square brackets are needed only if the template is going to be used for creating new databases. The brackets are required for these entries. For more information about rolling out an application, see Managing Domino Databases.

Pilot testing an application


Once your application has been reviewed, pilot test it with a few users. Make sure that the application works correctly and that all instructions are clear. Because the application users have a different point of view, they often uncover problems missed during the review cycle. Only the people specifically assigned to pilot test the application should have access to it. The default access should be - No Access. Then you can assign specific access levels and privileges to make sure that certain users can access only what they should. Make sure you retain Manager access, so you can make changes to the access control list during the test period and solicit comments from the testers.

Chapter 14: Completing an Application and Managing Design Changes 389

To pilot test an application 1. Choose File - Database - New Copy to make a local backup copy of your application. Use this backup copy if you need to backtrack from changes made during the pilot test. 2. Write an About This Database document to explain that the application is in the testing phase. Give users your name, e-mail address, and phone number, so they can contact you with questions, comments, and suggestions. 3. Add a Comment form to make it easy for testers to give you feedback. Include the comment form in at least one view. (Make sure that the comment form is marked in the form design to be included on the Create menu, or that a button or action is available to the user to compose the form.) 4. Choose File - Database - Access Control to add testers to the access control list. Be sure to retain Manager access for yourself. 5. Ask your Notes administrator for write access to a server for the pilot test. Tell the administrator which users need access to that server during the pilot test. 6. Choose File - Database - New Copy to copy the application to the server. Test the application on a single server. Do not create replicas yet. 7. If the database will involve replication later on, either to mobile laptops or between servers, confirm that the replication formulas are working and that servers can handle the volume of replication. For example, an annual review system places a demand on the server during the review writing time, but not at other times. If users will be replicating, then the pilot needs to confirm that replication instructions are appropriate for the levels of user expertise. While the initial part of the pilot test may be limited to a single server, if the intended implementation involves multiple servers, then the pilot needs to address some of these issues as well. See Managing Domino Databases for additional help on replication. 8. Keep track of questions that people ask about the function or use of the database. Their questions may include the Using This Database document or to the design of the database. For more information on copying a new database to a server, see Managing Domino Databases.

390 Application Development with Domino Designer

Renaming a database
If you want to change the title of a database as it appears in the Bookmark bar, you can edit the title. 1. Open the database. 2. Choose File - Database - Properties. 3. Enter a new database title. A database name or title is not the same as the database file name. The file name associated with a database is permanent. The only way to change the file name is to make a copy or a replica of the database and give the new database a different file name.

Renaming design elements


1. Open a database in Designer. 2. In the Design pane, click the type of design element youre working on. 3. Double-click the name of the design element in the Work pane. 4. Choose Design - <design element name> Properties to open the Properties box for the design element. 5. Edit the name of the design element. 6. Close and save the design element.

Design synopsis
The Design Synopsis dialog box lets you generate a detailed report on a particular database. Design Synopsis lets you: Gather information on a database Select the design elements you want in your report Filter the contents of the report so that you do not automatically get a lengthy report Choose to have the report appear on the screen or have it written to a specified database

Chapter 14: Completing an Application and Managing Design Changes 391

To create a design synopsis


1. Open the database for which you want a report. 2. Choose File - Database - Design Synopsis or select Synopsis in the Design pane. The Design Synopsis dialog box appears with the following tabs: Design Elements Database Information Content Output 3. Click the Design Elements tab: Select design elements one at a time from the list box. If you want every element of every design to appear, select All from the list box. Choose the specific elements that appear for each of the design elements. For example, if you selected Forms in the list box, all the forms in the database are listed. Select the ones you want in your report. The Add button lets you add specific elements one at a time to your report. The Add All button adds all the elements of a particular design element (for example, all the forms). Your selections appear on the right. If you want to add every element of every design element, choose All from the design list box and then click the Add All button. 4. Click the Database Information tab. Then, check the appropriate boxes to include information in your report on the following topics: General information gives information such as the database title, location, and categories. Space usage calculates information such as the file size, number of documents, and space used by the database. Replication gives information on the replication settings for the database. Access list generates a list of users, groups, and servers in the ACL and specifies assigned access levels and access roles for each.

392 Application Development with Domino Designer

5. Click the Content tab. Then do the following: Check the details you want on each design element. For example, for Forms, you can check Form Alias and Last Modification. Those details appear for each selected form in the database. Check the appropriate boxes so that your report will include information on subcomponents (such as formulas), LotusScript code, Java code, HTML code, or JavaScript code. 6. Click the Output tab. Then do the following: Choose to have blank lines or page breaks as report separators. Check the Write Output to Database box if you want to write the report to a database. If you check this box, a new dialog box appears letting you specify the database where you want the output written. 7. Click OK to generate the report. Unless you chose to have the report written to a database, the generated report is displayed in a new window. You can print it or save it in a file.

Updating documents after redesigning a form


When you redesign a form, be aware of the effect on existing documents. Some form changes, such as formatting changes, automatically display when users open an existing document. Other changes, such as adding a new field, do not display in existing documents until you update the documents by manually editing and resaving them or by running an agent. If the database replicates, redesign the form on only one database and let the changes replicate to other replicas.

Form changes that dont require updates to existing documents


As long as the form doesnt have the Store form in documents property set, the following changes display automatically in existing documents. When users open a document, they see the changed format. Changing a computed field formula Changing static text on the form Changing pop-ups Changing text properties and formats Changing form actions and buttons Changing graphics Changing the form name (if you leave the original name as a synonym to the right of the | symbol)
Chapter 14: Completing an Application and Managing Design Changes 393

Form changes that require updates to existing documents


Adding a new field Changing the field data type Changing a field name Deleting a field Changing the form name (if you dont leave the original name as a synonym) Changing the form type for example, from Main to Response Changing a form that has the property Store form in document

Checking field values in a document


Open the Document Properties box to see if a document contains a particular field or field value, or to troubleshoot a field that is not calculating its value correctly. A null value () indicates that the field is empty. A document always contains fields you design as well as fields Domino automatically generates. Most fields generated by Domino start with $. The following Domino-generated fields are useful fields to know about: $File shows an entry for each attachment in the document. $Links shows an entry for each link in the document. $Readers lists authorized readers if the document contains a read access list. $Revisions lists the date and time of each editing session since the first time the document was saved. $Title, $Info, $WindowTitle, $Body, and $Actions are associated with a form that is stored in the document. $UpdatedBy lists the document authors and editors. Anonymous forms dont have this field. Form indicates the name of the form used to create the document or the name of the form most recently used to save the document. Use the form in views to select documents created with the form. PostedDate indicates that a document has been mailed and shows the time and date it was mailed.

394 Application Development with Domino Designer

To check field values in a document: 1. Select the document in a view. 2. Choose File - Document Properties. 3. Click the Fields tab. 4. Click a field name in the left column to display the field.

Using agents to update documents affected by form changes


To update multiple documents affected by form changes, use an agent. To do so, it is best to create unshared agents and run them manually.

Editing and resaving documents


To save the step of editing and resaving documents manually, create an agent that uses the formula:
@Command([ToolsRefreshAllDocs])

Adding a field
If you create a new field, create an agent that inserts the new field into existing documents using the formula:
FIELD New field name := value;

where New field name is the name of the field and value is the value you want the field in these documents to have. The value can be the field default value; a formula that calculates the value; or a null value () that inserts the field into the documents, but doesnt give them any initial value.

Removing field data from all documents


If you delete a field, existing documents continue to store the obsolete field and its values. This unnecessary storage can affect disk space. To remove the obsolete field, create an agent that uses the formula:
FIELD Field name := @DeleteField;

After you run the agent, compact the database to reduce the actual file size of the database.

Chapter 14: Completing an Application and Managing Design Changes 395

Renaming a field
If you rename a field, existing documents continue to refer to the old field name. To update documents to refer to the new name, create an agent that uses the formula:
FIELD New field name := Old field name; FIELD Old field name := @DeleteField;

where New field name is the new name for the field, and Old field name is the original name for the field.

Reassigning documents to another form


If users attempt to open documents created with a deleted form, they see a message indicating that the form cannot be found. To prevent users from seeing this message, use these agent options to reassign existing documents to another form. These options appear when you click on Agents in the Design pane and then double-click an agent listed in the Work pane: 1. Under Which document(s) should it act on, select All documents in database and click Add Search. 2. Select By Form Used, select the name of the obsolete form, and click OK. 3. In the Programmers pane, click Formula and enter: FIELD Form := Reassigned form name; where Reassigned form name is the name of the form that the documents should use.

Removing the stored form from documents


In designing mail-enabled applications in which users need to see a document and dont have the original form stored in their mail databases, select the form property Store form in documents. This form property is permanently attached to all documents created with the form. To remove the stored form, remove all internal fields connected with the form by creating an agent that uses the formula:
SELECT $TITLE="Old form name"; FIELD $TITLE:=@DeleteField; FIELD $INFO:=@DeleteField; FIELD $WINDOWTITLE:=@DeleteField; FIELD $BODY:=@DeleteField;

396 Application Development with Domino Designer

FIELD $ACTIONS:=@DeleteField; FIELD FORM:="New form name";

This formula removes all internal fields attached to the documents where Old form name is the name of the form used to create the documents. The last line creates a FORM field where New form name is the form that will display the documents in the future. After you run the agent, compact the database to reduce the actual file size of the database.

Templates
A template is a skeleton that contains design elements, but no documents. When you use a template to create a database, the database receives the design elements from the template. You can use the Designer templates as is or customize them. Or, you can create a template by creating a database with the .NTF file extension and the Database is a template property. This property enables the master template to distribute design changes automatically to databases created from it. Databases that inherit their designs from master templates receive the latest changes through a nightly server task. If, for some reason, you do not want to automatically inherit designs via the nightly server task, you have two options: (1) do not put the template on a server that runs the nightly update task or (2) do not set the Database is a template property. You can then distribute changes to the database design by using the Replace Design command, specifying the server where the template is located and selecting the template. Make sure to set the database properties so that the database does not automatically inherit the design via the nightly server task.

Converting a database to a template


Open the database you want to be a template and choose File - Database Properties. 1. Click the Design tab. 2. Select Database is a template. 3. Enter a template name (with no spaces in the name) and click the green check mark to confirm it. 4. (Optional) Select List as advanced template in New Database dialog to hide the template unless users select Show all templates in the New Database dialog box.

Chapter 14: Completing an Application and Managing Design Changes 397

You can use letters, numbers, and underscores in the name. Choose a concise, descriptive name that is easy to remember and type. Choose a name that indicates the application type or design elements represented in the template. For example, StdR5Disc represents a standard Notes template containing the design for a Discussion (R5) database. The master template name, the title, and the categories assigned to the database cannot add up to more than 99 characters.

Creating templates
Using a template, you can establish design standards for use throughout your company. In large companies, a central development group usually designs and manages templates to provide consistent designs and speed up distribution of new databases. Use a template to standardize similar types of applications for example, all discussion databases or to store individual design elements, such as fields, forms, views, folders, navigators, and agents that you can use in a variety of applications. To customize a Designer template, use File - Database - New Copy to copy the original template and inherit the original design. Give it a different file name in the Copy Database dialog box to prevent future releases from writing over your customized template. Heres a list of changes you might make when you customize a Designer template: Leave the original Designer template properties alone so that existing databases that inherit their design will continue to be synchronized to the template. Change the newly copied template file name in the Copy Database dialog box (File - Database - New Copy) to a name that indicates its intended use. Change the newly copied template name (File - Database -Properties) to a new name, indicative of the new template purpose. If existing databases that inherited the original Designer template design need to inherit the design from the newly created template, edit the database properties of those databases to reflect the name of the newly copied template.

398 Application Development with Domino Designer

Advantages of standardizing with templates


Anyone can quickly and easily create a new database Users need to know only one command: File - Database - New. They never have to modify the design and dont need to know anything about database design. Developers and experienced users can save design time Forms, views, and agents copied from a template require no additional design work or updates. Using a predesigned form or view that contains complex formulas or a large keywords list reduces the chance of design errors and requires less testing time before database rollout. Databases appear consistent to users View, forms, and fields associated with a template use the same names in all databases. This allows users to apply their knowledge of one database to many databases. Note The template does not usually control the database icon, the About This Database document, and the Using This Database document. If you want an icon, About document, or Using document to inherit all design changes, go into Designer, choose Resources- Other, select the icon or document, and make change in the Properties box so that changes are inherited from the template. The default is not inherited. You can also change these design elements by manually copying and pasting the redesigned elements into databases linked to the template. In addition, do not create private agents or folders in templates; their changes cant be distributed automatically. If a private agent or folder exists in a template, you receive error messages when the design is refreshed/replaced. In the case of a shared/private-on-first-use folder: if the folder in the template has been opened or tested, a private folder exists and that folder generates errors when you try to refresh a design. Examples: Creating templates A customized discussion template Suppose you need to add a Confidentiality field to all discussion databases, so that authors can mark specific documents as Confidential For internal use only. All databases that base their design on the Discussion template will inherit this field. Add the field directly to the Designer Discussion template. Every database associated with the template inherits the new Confidential field. DISCSW50.NTF (StdR5Disc) |- SALES.NSF Sales discussion inherits from StdR5Disc |-TRAVEL.NSF Travel discussion inherits from StdR5Disc
Chapter 14: Completing an Application and Managing Design Changes 399

A spinoff template Most users mail databases inherit their design from the standard Notes mail template, but the Eastern region employees need a Reply to Customer form in their mail databases. Make a copy of the Notes mail template to use as a base for the Eastern mail template. You inherit the design from the Notes mail template, but after creating the Reply to Customer form, you click Prohibit design refresh or replace to modify in the Design Document Properties box so the form wont be deleted when the server resynchronizes the design of mail databases. The Eastern regions template inherits its design from the Domino mail template and also serves as a template itself. MAIL50.NTF (StdR5Mail) |-SLEE.NSF Sam Lees mail inherits from StdR5Mail |-EASTMAIL.NTF (StdEastMail) Eastern mail template inherits from StdR5Mail |- SBRAUN.NSF Sandy Brauns mail inherits from StdEastMail A designers notebook You create a new template called DesignNotebook to store centralized information, such as employee names and product numbers, as well as generic design elements, such as Main Document forms and All by Category views. Developers and experienced users browse through the Design Notebook when they create a new database and copy and inherit elements to speed up their design work. DESIGN.NTF (DesignNotebook) |- Suggestion Box: Inherit the All by Category view from DesignNotebook |- Employees Directory: Inherit the Employee Information form and EmployeeID field from DesignNotebook |- Product Catalog: Inherit the Product ID Update agent from DesignNotebook

400 Application Development with Domino Designer

Creating a design library template


If you have several design elements that you want to copy to different databases, you can create a library of design elements. You do this by creating a template that contains all of these design elements. That way, if you want to copy a design element to a new database, you maintain a connection to a source template. This allows you to have a design library template that is maintained and updated centrally and have the changes automatically propagate to all databases that you choose to inherit from that template. This is especially useful if you have forms or images that will be common to a number of different databases that need occasional updating, such as company logos or order forms.

To create a design library template 1. Create a new blank database with the file extension .NSF. 2. Copy the individual design elements into the template. 3. On the Design tab of the Database Properties box, select Database is a template and enter a template name. 4. On the Design tab of the Database Properties boxes of the databases that will inherit these design items, select Inherit design from template and enter the template name.

Chapter 14: Completing an Application and Managing Design Changes 401

Linking a database to a template


You can link a new or existing database to a template. To link a new database to a master template When you create a database from a template, select Inherit future design changes in the New Database dialog box to create the link. When you create a replica (File - Replication - New Replica) or a copy (File Database - New Copy), the new database automatically links to the same template that the original database uses. To link an existing database to a template If you link an existing database to a template, the database design is replaced when the servers Design task runs, or when you manually refresh the design. Thereafter, the design remains synchronized with the template. 1. Select the template and choose File - Database - Properties. 2. Click the Design tab. 3. Highlight the name in the Database is a template box, and press CTRL+C to copy it. 4. Select the database you want to link. 5. Select Inherit design from template on the Design tab in the Properties box. 6. Click the Template Name box, and press CTRL+V to paste the name.

Linking individual design elements to a template


To link individual forms, views, navigators, pages, and other design elements to a template, copy the design element from a template or from a database that inherits its design from a template. Then paste the element into another database. You can also set up the link for existing design elements in a database to a template. To link a copied design element to a template When you copy a design element from a template or from a database linked to a template, the copied element automatically links to the template if you answer Yes when prompted about inheriting future design changes.

402 Application Development with Domino Designer

To link an existing design element to a template If you link an existing design element to a template, the design is replaced when the servers Design task runs or when you manually refresh the design. Thereafter, the design element remains synchronized with the template. 1. Select the master template and choose File - Database - Properties. 2. Click the Design tab. 3. Highlight the name in the Database is a template box and press CTRL+C to copy it. 4. In Designer, open the database containing a design element you want to link. 5. In the Design pane, select the type of design element youre designing. 6. Select the name of the design element in the Work pane. 7. Do one of the following: For an agent, choose Agent - Agent Properties. For other design elements, choose Design - Design Properties. 8. Click the Design tab of the Design or Agent Properties box. 9. Click Inherit from the design template and press CTRL+V to paste the name.

Making and distributing design changes


When you need to redesign an application, make and distribute the changes in one of these ways: Make design changes directly in an independent database on the server. This technique combines making and distributing design changes in one step. Use this technique only if a small group of people uses the database and it exists on only one server. Make design changes in a template and then use Replace Design to distribute the template design to the database. Make design changes in a master template (sometimes called a design template). Use the Design server task or Refresh Design to distribute the master template design to databases that inherit their design from the master template. Using a master template to manage design changes is best in larger organizations where you need to control, track, maintain, and synchronize design changes in a structured way. For small

Chapter 14: Completing an Application and Managing Design Changes 403

organizations, using a template or a master template is a matter of preference. This figure below summarizes the steps you take to make and distribute design changes:

Replication is the process by which database replicas on multiple servers synchronize their data and their designs automatically. Its important to understand which design changes replicate and which dont and how the database access control list and other replication settings affect the distribution of design changes.

Refreshing a design
Refreshing a design updates a database whose design is linked to a template. Design elements that prohibit design replace or refresh are not included in the updates.

Automatically refreshing a design


The Design server task automatically synchronizes all server databases that are linked to a template. This server task runs by default at 1:00 A.M. For the update to work, a template must reside on the same server as the databases linked to it. Replicas synchronize with the templates stored on their servers.

404 Application Development with Domino Designer

Manually refreshing a design


Use the Refresh Design command to distribute design changes manually from a template to any databases linked to it. Manually refresh the design of a database when: The database is stored locally; therefore, the nightly Design server task doesnt update the design. You want to receive design updates before the scheduled update. You dont have Designer access to the template.

Components that are not refreshed


The following are not changed during an automatic or manual refresh procedure: The database icon (unless you have disabled the Prohibit design refresh or replace to modify box in the Design Properties box) The database title and category The property List as advanced template in New Database The database ACL and encrypt database settings Using This Database and About This Database documents (unless you have disabled the Prohibit design refresh or replace to modify box in the Design Properties box) Individual elements whose design is protected from updates (that is, if Prohibit design refresh or replace to modify is selected on the Design tab of the Design Properties box for the element)

Components that are refreshed


The following components are changed during an automatic or manual refresh procedure if the design element changes in the template: Forms, fields, form actions, and event scripts Views, folders, and view actions Agents Pages Framesets Navigators Shared fields File - Database Properties selections, except the advanced template option

Chapter 14: Completing an Application and Managing Design Changes 405

Refreshing a design manually


1. Select the database to be updated, and choose File - Database - Refresh Design. 2. Select the Domino server that stores the template(s) or select Local if the templates are on your workstation, and then click OK. 3. Click Yes to confirm. 4. Repeat Steps 2 and 3 if other templates associated with the database are stored on other servers.

Replacing a design
The Replace Design command makes a database identical to a template and is the only way to distribute design changes if the database doesnt inherit its changes from a template. If you have at least Designer access in the database ACL, you can replace the design of a database with the design from a template.

Components that are not replaced during Replace Design


The following components are not changed during a Replace Design procedure: The database icon (unless you have disabled the Prohibit design refresh or replace to modify box in the Design Properties box) The database title and category The property List as advanced template in New Database The database ACL and encrypt database settings Using This Database and About This Database documents (unless you have disabled the Prohibit design refresh or replace to modify box in the Design Properties box) Individual elements whose design is protected from updates (that is, if Prohibit design refresh or replace to modify is selected on the Design tab of the Design Properties box for the element)

406 Application Development with Domino Designer

Components that are replaced during Replace Design


The following components are replaced during a Replace Design procedure: Forms, fields, form actions, and event scripts Pages Views, folders, and view actions Agents Navigators Framesets Shared fields File - Database Properties selections, except the advanced template option To replace the design of a database If a database replicates to other servers, replace the design of only one database and let the changes replicate to other replica databases. 1. Select the database on the server and choose File - Database - Replace Design. 2. Select the template. 3. Click Replace and Yes to confirm.

Design changes and replication


Unless you distribute design changes through templates, design changes and any document updates made in one database replicate directly to replicas, as long as servers have Designer access or greater in the database ACL. To avoid replication conflicts and unexpected changes, only one person the database designer or manager should make design changes to only one database and maintain its design. Then let replication distribute the design changes to other replicas. Replication occurs at the times specified by the servers replication schedule. Replicating design changes can take several hours or even a full day if replicas are in different locations and arent replicated frequently.

Chapter 14: Completing an Application and Managing Design Changes 407

Templates and replication


When you use a template to distribute design changes, you must place a replica of the template on each server that has databases that inherit their design from the template. Give servers Designer access or greater in the database ACL of each replica. To avoid replication conflicts, make changes to one template on a source server. Then let replication distribute the design changes to template replicas. The updated template replicas then refresh the design of linked databases on the server. To distribute design changes efficiently, the source server should replicate the template replicas before the Design task runs on each server at 1:00 A.M. Any updates youve made to documents replicate directly with other database replicas. For more information about replication, see Managing Domino Databases.

Preventing design changes


Use these methods to protect a customized design from accidental changes. Note None of these choices prevents someone with Designer or higher access in the database ACL from changing the design. To prevent all design changes, hide the design of the database.

Protect an individual design element from being replaced or refreshed


This is useful to protect customized design elements from being overwritten in a Replace Design procedure and to protect a customized design element in a database that is linked to a template. 1. Open a database in Designer. 2. In the Design pane, click a design element. The names of all the design elements of that type appear in the Work pane. 3. In the Work pane, select the name of the design element you want to protect. 4. Choose Design - Design Properties (or for agents choose Agent Agent Properties). 5. Click the Design tab. 6. Select Prohibit design refresh or replace to modify.

408 Application Development with Domino Designer

Unlink individual design elements from a template


This breaks the link between a design element and a template and is useful when you want to customize a design element that you copied from a template. Future changes to the design element in the template wont affect the design element in your database. 1. Open a database in Designer. 2. In the Design pane, select a design element. The names of all the design elements of that type appear in the Work pane. 3. In the Work pane, select the name of the design element you want to unlink. 4. Choose Design - Design Properties (or for agents choose Agent Agent Properties). 5. Click the Design tab. 6. Remove the name of the template in the Inherit from the design template box.

Unlink a database from a template


This breaks the link between a database and a template and is useful when you want to customize the design of an entire database. Future changes to the template wont affect the database. 1. Open the database and choose File - Database - Properties. 2. Click the Design tab. 3. Deselect Inherit design from template.

Hiding the design of a database


To prevent users from making any design change to a database, hide the database design. Hiding the design permanently disables all design operations and hides all formulas and scripts. Even users who have Designer or Manager access to the database cant make design changes. This feature is useful for hiding the design of ready-to-use databases that are based on a template you own. When design changes are required, you redesign the template, whose design is not hidden, and then refresh the design of the linked databases. To maintain maximum design security, do not give the template to anyone except authorized designers, and do not distribute documentation for the formulas and LotusScript programs.

Chapter 14: Completing an Application and Managing Design Changes 409

When you hide a database design, users cannot: View the settings for design elements (View - Design disappears from the View menu) Modify, add, or delete fields, forms, navigators, pages, or subforms Modify or delete existing views View, delete, or modify existing agents or add shared agents View or change formulas, LotusScript programs, or formulas associated with simple actions Change the Database Open properties Display a synopsis of the design Reveal the design of the database by making a copy or replica of it To hide the design of a database This procedure assumes youre hiding the design of a database that inherits from a template. Thoroughly review, debug, and pilot test the template before proceeding. 1. Create a new database based on the template. 2. After the database is created, select the new database and choose File Database - Replace Design. 3. Select the template and select Hide formulas and LotusScript and Inherit future design changes. 4. Click Replace and Yes to confirm.

Building in access to agents before hiding the design


If an agent in the application requires user input, such as specifying a database on which to run or changing schedule options, you must select the schedule option Choose when agent is enabled. Create a button or form or view action that includes a formula using @Command[AgentEnableDisable] to enable the agent automatically.

410 Application Development with Domino Designer

Hiding design elements


You can hide most design elements so that users cant see them on menus or lists. You do this in the Design tab of the Properties box for the design element or agent. Choose from these options at the Design tab: Hide design element from Choose Web browsers to hide a Notes-only design element from Web users. Choose Notes R4.6 or later to hide a Web-only design element from Notes users. Choose both options to hide the design element from all users. This is useful when a design element launches only from a button or a formula, or if you designed the element for purposes that users dont need to know about. Do not show this design element in menus of Notes R4 or later clients Use this to hide older design elements from Notes Release 4 users. Hidden design elements are hidden from the server too; you cant use Domino URL commands to access documents in hidden views or forms. Tip To hide a design element that isnt needed by users but is used for background processes, such as lookup formulas, enclose the design element name in parentheses for example, (Lookup View) instead of using Hide tab options. To hide design elements 1. Open a database in Designer. 2. In the Design pane, select a design element. 3. In the Work pane, select the name of the design element you want to hide. 4. Do one of the following: For an agent, choose Agent - Agent Properties. For other design elements, choose Design - Design Properties. 5. Click the Design tab. 6. Choose the appropriate Hide options.

Chapter 14: Completing an Application and Managing Design Changes 411

Chapter 15 Creating a Workflow Application

Workflow Overview
Workflow applications let you automate tasks. These tasks most often involve automatically sending mail messages or automatically routing documents, such as tracking orders and reviewing project plans. Any project requires that one person or a number of people complete a series of tasks; workflow applications guide the project through these tasks automatically. Workflow applications reduce overhead and errors, speed processes, and track the status of a project. For example, a workflow application might automatically send a document in a publishing company from writer to editor to proofreader to production. At each stage, an individual is responsible for specific tasks related to that document. Once the task is complete, the workflow application ensures that the individuals responsible for the next task are notified and receive the data they need to execute their stage of the process. Examples of Workflow Applications The Document Library R5 template (doclbw50.ntf) and the Teamroom R5 template (teamrm50.ntf) are examples of applications that include workflow. For both templates, the document you want reviewed is kept in a central database and is not mailed to reviewers. Reviewers receive mail notifying them of the need to review. Included in the mail may be a doclink to the document. The Document Library template uses a review cycle so that you can route a document link to a series of recipients. It allows serial and parallel reviews. With parallel reviews, every reviewer receives e-mail notification at the same time. With serial reviews, you do not want all reviewers commenting on the document at the same time. Reviewers receive e-mail notification at different times. The Teamroom template features parallel review processing. It also allows the automatic mailing and archiving of newsletters and memos. See the Domino Designer Templates Guide for additional information on these templates.

413

Planning workflow
Before you select the type of mailing features that suit a workflow application, you should carefully plan the actual workflow. One way to implement a workflow application is to collect information from the databases of an application into a central, shared database and then distribute the information through e-mail to the appropriate individual users. Another way to implement a workflow application is to send documents automatically from one user to another for their review. Users working in a shared database can create and edit documents directly in the database. Remote users must dial into the server database regularly to contribute. Designers can implement automatic e-mail notifications to alert users to documents in the database that need their attention. To automate the process, you can build e-mail notifications into forms or agents. To make it easier for users, the notifications often include document links. For the convenience of remote users, you might include a copy of the document within the e-mail notification instead of a link to the document. If users work in individual mail databases, they can create and respond to documents and then route them to each other or to a central mail-in database. Automated, easy-to-use forms that are stored in documents are typical of such applications. Of course, if you are sending individual mail messages, you are increasing disk space because the form is stored with the document. The following table summarizes the advantages and disadvantages of these two approaches.
Method Central Shared Database Central shared database; e-mail notices that link to documents Alerts users to work that needs their attention or items of interest in a central database; places least burden on network resources and conserves server disk space; users get to see each others review comments. Requires network access or remote access through a modem Advantages Disadvantages

continued

414 Application Development with Domino Designer

Method Individual Mail Databases Sending multiple documents

Advantages

Disadvantages

Easier for remote users because they only need to access mail instead of accessing a remote database.

Workflow process may take longer since work is done sequentially; requires more server disk space than a central database because forms must be stored with documents; replication times may be longer because of document size.

Features that support automatic mailing


You can add automatic mailing to a database either at the form level or through automation features such as form and view actions, agents, and events.

Sending links to documents


In a workflow application, you may want to mail notices of new or modified documents or reminders of work that needs to be done. Sending links instead of documents saves time and space. To do so, create an agent, event, form or view action, hotspot, or button that uses one of the following: The simple action Send Mail Message with Include link to document selected. The simple action Send Newsletter Summary. The formula function @MailSend with the [IncludeDocLink] flag. A LotusScript program that uses the Send method in either the NotesDocument class or the NotesUIDocument class and the FormatMsgWithDoclinks method in the NotesNewsletter class. A Java program that uses the Send method in the lotus.notes.Document class and FormatMsgWithDoclinks method in the lotus.notes.Newsletter class.

Chapter 15: Creating a Workflow Application 415

Sending documents
It makes sense to build in features for mailing documents in the following situations: Users work on documents sequentially from their individual mail databases You want to send documents to a mail-in database The form must have a SendTo field that specifies the recipients, unless you use a formula or program that includes the SendTo information. Use any of these methods: Add a MailOptions field with a value of 1 to force the document to be mailed when it is saved. Select the form property On Close: Present mail send dialog to let users decide if they want to mail the document. Create an agent, event, form or view action, hotspot, or button that uses: The simple action Send Document The formula functions @Command([@MailSend]) for optional mailing or @MailSend for automatic mailing A LotusScript program that uses the Send method of the NotesDocument class or the NotesUIDocument class A Java program that uses the Send method of the lotus.notes.Document class In addition, all forms and views contain the default action Send Document that you can display in the Actions menu or the action bar.

Enabling users to view documents


To allow users to view mail-enabled documents, do one of the following: Copy the form into the master mail template on the server and refresh the design of mail databases. Select the Store form in document option for the form.

416 Application Development with Domino Designer

Forwarding documents in a mail memo


Use mail forwarding to mail documents that dont have a SendTo field. Create an agent, event, form or view action, hotspot, or button that uses one of the following: The simple action Send Mail Message with the option Include copy of document selected The formula function @Command([MailForward]) A LotusScript program that uses the Forward method in the NotesUIDocument class In addition, all forms and views contain the default action Forward that you can display in the Actions menu or the action bar.

Sending replies to a mail memo


To activate a message to a mailed document, create an agent, event, form or view action, hotspot, or button that uses the simple action Reply to Sender.

Mailing features and Web applications


Web users whose mail databases reside on a Domino server can participate in mailing processes. When you are designing forms or views, include form or view actions as alternatives to menus for tasks Web users need to do. For example, you can create a Send Document action so that it appears on the action bar of a form both in Notes and on the Web.

Fields that control mailing options


To build mailing options into a form, create fields that have reserved names in Designer. When you create a field with one of these reserved names, built-in programming takes care of the task for you. The fields can be text or choice list fields that use predefined values. For information on text fields, see the topic Text and rich text fields. For information on choice list fields, see the topic Displaying lists of choices. For information on editable and computed fields, see the topic Editable and computed fields.

Chapter 15: Creating a Workflow Application 417

Table of fields that control mailing options


Reserved Field name BlindCopyTo CopyTo DeliveryPriority Encrypt MailFormat Values The name(s) of a person, group, or mail-in database. The name(s) of a person, group, or mail-in database. L, N, H 1, 0 B, E, M, T Values correspond to: Low, normal, or high-priority. Use 1 to encrypt mailed documents. Enables cc:Mail users to view Notes documents in a variety of predefined formats: B = both text and encapsulated. E = encapsulated in a Notes database, which is attached to the cc:Mail memo. M = mail. Body field of document is text and pasted into cc:Mail memo. T = text. Contents of the document are rendered as text and pasted into the body of the cc:Mail memo. MailOptions ReturnReceipt 1, 0 1, 0 Use 1 for automatic mailing. Use 1 to send a receipt when document is opened by the recipient. Use 1 to save mailed documents. Comments

SaveOptions SendTo Sign

1, 0

The name(s) of a person, Required for all forms that mail group, or mail-in database. documents. 1, 0 Use 1 to an add electronic signature to fields. (Only applicable if a form also contains sign-enabled fields.)

If you write a LotusScript program that uses the Send method of the NotesDocument class or a formula that uses @MailSend, you can include many of the above mailing options in the script or formula. For more information on using LotusScript, see the Programming Guide.
418 Application Development with Domino Designer

Interactions with the Mail Send dialog box The MailOptions field with a value of 1 overrides the users choices in the Mail Send dialog box if the form is set to enable optional mailing. With a MailOptions field set to 1, users can click Yes to save the document, No to close without saving, or Cancel to return to the document. The Sign, Encrypt, and SaveOptions fields with values of 1 override the property On Close: Present mail send dialog in the Form Properties box, but they do not actually change what is displayed to users in the Mail Send dialog box. Interactions with the Document Save dialog box The values in SaveOptions, Sign, and Encrypt fields override the users settings in the Document Save dialog box. MailFormat A computed MailFormat field can have one of the following values: Encapsulated (E) The document is encapsulated in a database, which is attached to the cc:Mail memo. The cc:Mail recipient must have the Notes client installed on the workstation. This preserves the document exactly as it looks in Notes. To read the document, the cc:Mail user double-clicks the icon representing the attached database; this launches Notes and opens the database. Use this format only if information will be lost if the document were to be converted to Text or Memo format. The Encapsulated format creates larger documents, so it uses more server disk space. To ensure that the document is displayed correctly when a cc:Mail recipient starts Notes, assign the form property Store form in document in the Form Properties box. Text (Text) The contents of the document are rendered as text and pasted into the body of the cc:Mail memo. The cc:Mail recipient can read the document without using Notes. Since the document is rendered as text, you do not need to store the form in the document. Both (B) The document is both rendered as text and encapsulated in a database. This ensures that cc:Mail recipients can read the document even if they do not use Notes. Mail (M) The Body field of the document is rendered as text and pasted into the cc:Mail memo. Use this format only with documents that were created using a form that contains a field named Body.

Chapter 15: Creating a Workflow Application 419

Since the document is rendered as text, you do not need to store the form in the document. MailOptions The MailOptions field with a value of 1 overrides the property On Close: Present mail send dialog in the Form Properties box. With a MailOptions field set to 1, users can click Yes to save the document, No to close without saving, or Cancel to return to the document. To add the mail signing and encryption options, create editable keywords fields named Sign and Encrypt. SendTo The Allow multi-values and Allow values not in list are useful for SendTo fields. Examples: Fields that control mailing options An editable SendTo field with a default value You want to give users the name of the mail-in Employee Survey database, and the option of mailing surveys to other people. Create an editable SendTo field, select Allow multi-values, and write a default value formula that includes the mail-in database name, enclosed in quotation marks. A hidden SendTo field with a single recipient Sandy Brown needs to receive all documents saved in the Marketing Statistics database. Add a hidden Names field called SendTo to the Statistics form. The field formula contains the recipients name and domain enclosed in quotation marks. The recipients domain is required if the recipient isnt in the same Notes domain from which the document is sent.
"Sandy Brown @ Marketing"

A formula that calculates recipients and sends a document Approvers want to receive new travel requests from employees by e-mail. On the Travel Request form of the Employee Expenses database, create hidden text fields called SendTo, Subject, and Remark. The field formula below calculates the names of approvers and sends the original document as a link when the document is saved for the first time.
REM "Send mail to approvers the first time the doc is saved"; REM; SendTo :=@Unique(@Trim(ApproverName_1 : ApproverName_2 : ApproverName_3)); Subject := "Travel Request for " + TravelerName + "requires your approval"; Remark := "A Travel Request has been entered for " + TravelerName + ". Your approval is required. Please double-click the following link and approve or reject the request."; 420 Application Development with Domino Designer

REM; @If(@IsNewDoc & @IsDocBeingSaved; @MailSend(SendTo; ""; ""; Subject; Remark; "";[IncludeDoclink]); "")

Displaying the MailSend dialog box


If you want the Mail Send dialog box to appear so that users have the option of mailing, saving, signing, or encrypting a document, do one of the following: Select On Close: Present mail send dialog in the Form Properties box on the Defaults tab. Write a formula that includes @Command([MailSend]). Make sure that you include a SendTo field on the form.

Creating a database that receives mailings


A mail-in database document in the Domino Directory allows a database to receive mailed documents. The server administrator creates the mail-in database document: 1. Open the Domino Directory and choose Create - Server - Mail-In Database. 2. Next to Mail-in name, give the database a name that identifies it in SendTo fields or in formulas on the form. 3. Next to Domain, enter the domain name if your organization uses multiple mailing domains. 4. Next to Server, enter the hierarchical name of the server on which this database resides. 5. Next to Filename, enter the database directory name (if the database is in a subdirectory of the Notes Data directory) and the file name. 6. (Optional) Click Administration, and next to Administrators enter additional names of people who can change this document. 7. Close and save the document.

Chapter 15: Creating a Workflow Application 421

Using an agent to send automatic replies


For a mail-in Survey database, for example, that collects employees responses about the companys benefits package, create an automatic response agent so employees receive a confirmation that the survey arrived. 1. Select the Survey database and choose Create - Agent. 2. Give the agent the name Send Thank-You and select Shared Agent. 3. Select the run option If New Mail Has Arrived. 4. Select Simple action(s) and click Add Action. 5. Select Reply to Sender and click Reply to sender only. 6. In the box for the body of the text, type:
Thank you for taking the time to respond to our survey. We will distribute the results as soon as they are ready.

7. Click OK. 8. Close and save the agent.

Using an agent to mail notices


Consider that every week, you want action items mailed from the Meeting Tracking database to the people who are assigned to each task. 1. Select the Meeting Tracking database, and choose Create - Agent. 2. Give the agent the name Mail Action Items and select Shared Agent. 3. Select the run option On Schedule Weekly and click Schedule. 4. Select On Wednesday, type:
5 PM

Then click OK. 5. Select All new and modified documents since last run and click Add Search. 6. Select Condition: By Form Used, select Action Item, and click OK. 7. Click Add Search and select Condition By Field and select Status, contains, Open. Click OK. 8. Click Simple action(s) and Add Action. 9. Select Send Mail Message and click More. 10. In the To box, click Formula and enter the formula:
AssignedTo

11. In the Subject box, click Formula, type this formula and click OK:
ActionItem + ", due " + @Text(DueDate)

422 Application Development with Domino Designer

12. In the Body box, type:


This action item has been assigned to you.

13. Select Include copy of document and click OK. 14. Close and save the agent.

Using an agent to send announcements


Consider that you are designing a Corporate Announcements database to which managers want to send notices for important announcements. To circulate particular announcements, managers select them from the view and then select the agent that sends notices. Tip To prevent non-managers from running this agent, deselect Create personal agents in the database access control list for all users except those with Manager access. 1. Select the Corporate Announcements database and choose Create Agent. 2. Give the agent the name Mail announcements and select Shared Agent. 3. Select the run option Manually From Agents List. 4. Select Selected documents. 5. Select Simple action(s) and click Add Action. 6. Select Send Newsletter Summary. 7. In the To box, type:
All Personnel

All Personnel is a group in the Domino Directory. 8. In the Subject box, type:
Important Announcements

9. In the Body box, type:


Please note the following new announcements:

10. Select Include summary for each document in view, select the All By Date view, and click OK. 11. Close and save the agent.

Chapter 15: Creating a Workflow Application 423

Chapter 16 Connecting to Enterprise Data

Accessing data in enterprise applications


Incorporating back-end data into everyday business processes maximizes the value of a Designer application. Designer includes a range of technologies for the security and control of business processes, forms routing, and approvals management. With enterprise integration technologies, you can incorporate traditionally difficult-to-reach data into your business applications. Using data integration tools and services, you can create applications that contain connectors to relational databases (such as Oracle and DB/2), Enterprise Resource Planning systems (such as SAP, PeopleSoft, and J.D. Edwards), and transaction systems (such as CICS, IBM MQSeries, and IMS). You can accomplish this either programmatically or with visual tools that work with native database drivers. The following connection solutions are available either as part of Domino Designer or as an add-on tool. @DB commands As in previous releases, you can use @DB commands and the LotusScript Data Object (LS:DO) to exchange data with relational databases using ODBC. For more information on @DB commands and LS:DO, see the Programming Guide. Domino Enterprise Connection Services (DECS) Domino Enterprise Connection Services (DECS) is a visual tool and high performance server environment you can use to create Web applications that provide live, native access to enterprise data and applications. The visual tool includes an application wizard and online Help to assist you to define external data source connections for example, DB2, Oracle, Sybase, File directory, EDA/SQL, or ODBC and fields within your application that automatically update with external connector data. For more information on connecting to legacy databases, see the Domino Enterprise Connection Services Users Guide.
425

LotusScript and Java classes LotusScript and Java include classes for enterprise data access. Use these classes to customize applications to incorporate information from relational databases, transaction systems, and ERP applications according to your business needs. The Domino Server includes the Lotus Domino Connector LotusScript extension, permitting programmatic access to Domino Connectors from LotusScript. For more information about the Domino Connector LSX, see the LotusScript Extension for Domino Connectors Reference Guide. The Domino driver for JDBC, providing standard JDBC access to data in Domino databases, is also available from the Lotus Web site at http://www.lotus.com. Using this driver, you can write Java applets and applications that use JDBC to access information in Domino databases. JDBC classes now ship with Domino in the java.sql classes. These classes may be used when writing Java agents to access relational data via standard JDBC drivers. For more information on LotusScript and Java classes, see the Programming Guide. Domino Connectors Domino Connectors are modules which provide native connectivity to external sources such as relational databases, ERP, or transaction systems. You can access these connectors through the forms-based development tool in DECS, or through the Domino object classes using LotusScript or Java languages. For more information on Domino Connectors, see the Domino Connectors Setup Guide. Lotus Enterprise Integrator Lotus Enterprise Integrator, previously called Lotus NotesPump, which is available separately, extends DECS functionality beyond real-time data sources to include support for high volume data transfer and synchronization. Lotus Enterprise Integrator provides visual tools to manage integration between data sources without programming, including the capability to initiate event-driven or scheduled high volume data transfers between Domino applications and relational databases and other enterprise applications. Lotus Enterprise Integrator also supports programmatic data transfers via LotusScript and Java Classes. For more information on Lotus Enterprise Integrator, see the Lotus Web site at http://www.eicentral.lotus.com.

426 Application Development with Domino Designer

Connectivity Solutions Description

Domino Version

DECS - Domino Forms-based development tool. Provides R4.6.2 Enterprise Connection live access to enterprise data and or higher Services applications, including relational databases, transaction systems, and Enterprise Resource Planning (ERP) systems. LS:DO - LotusScript Data Object LotusScript access to any ODBC-compliant R4.0 data sources. or higher

JDBC - Java Database Access from Java agents to R4.6 Connectivity relational data via Standard JDBC classes. A or higher JDBC to ODBC bridge also shipped as a part of Domino. Lotus Domino Connector LotusScript Classes Lotus Domino Connectors Unified object model with a consistent R4.6.2 interface to programmatically access or higher enterprise data and applications. These classes can be used with LotusScript or Java. Modules which provide native connectivity R4.6.2 to enterprise data sources. These connectors or higher can be accessed through Domino Enterprise Connection Services or programmatically through Domino classes. Connectors to DB2, Oracle, Sybase, Text & File based systems, EDA/SQL, and ODBC are provided with the Domino server. Premium connectors to ERP applications, Transaction Monitors, and Directory systems will be available separately. Note that the NotesSQL driver for ODBC access to Domino data is available for free from the Lotus Web site at http://www.lotus.com. LSX - LotusScript extensions Create custom objects that work natively with Domino applications as well as Java and OLE. Some examples of LSXs are MQSeries, SAP, DB2, and Rich text. The DB2 LSX will ship for Domino Release 5. These are classes for programming directly to the DB2 client access library. Lotus Enterprise Integrator (Lotus Notes Pump) Data distribution server that provides support for event-driven or scheduled high-volume transfer and data source synchronization. R4.0 or higher R4.0 or higher

continued

Chapter 16: Connecting to Enterprise Data 427

Connectivity Solutions Description Domino Connector Toolkit

Domino Version

Provide developers with tools and R4.6.2 information to build additional Domino or higher Connectors and classes available in Java or LotusScript.

Using ODBC to access relational databases


You can use the ODBC (Open Database Connectivity) Version 2.0 standard to access relational databases such as DB2 or Oracle. Using formulas or scripts embedded in Domino objects, you can integrate the data from many external databases into Domino applications. For example, a customer call-tracking application accessed via the Notes client or Web browser can access customer financial data from an ODBC-compliant relational database management system. ODBC is available on Windows, AIX, HP-UX, OS/2, and the Mac PowerPC. For more information on ODBC, see the Programming Guide. Files required to use ODBC When you install Designer, ODBC modules that support external data access install automatically. In addition to these modules, you need an ODBC library (or shared object) and a driver for the type of database you want to access. You purchase and install the library and driver separately. For Windows 95, for example, you need these modules on your workstation: The ODBC 2.0 interface, available from Microsoft. This defines the library of ODBC functions that perform the connection, query, and data-retrieval processes. The Driver Manager, available from Microsoft and other vendors. This loads the necessary drivers used to access the data and acts as an interface between Domino and the drivers. The ODBC drivers, available from third-party vendors or available at no charge to Notes and Domino users on the Lotus Web site. These handle communication between the Driver Manager and the databases. Domino supports a variety of drivers. Each driver affects the specific capabilities of your application and comes with its own installation, configuration, and Help documentation.

428 Application Development with Domino Designer

Note On 32-bit platforms, such as Windows 95, avoid having the 32-bit and 16-bit versions of drivers and driver managers installed with a 32-bit or 16-bit version of Domino installed. The two different types of software do not mix. When using 32-bit Notes clients or servers, use a 32-bit driver manager and 32-bit drivers. When using a 16-bit Notes client or Domino server, use a 16-bit driver manager and 16-bit drivers to use ODBC to make successful connections. Some Lotus applications include ODBC drivers that are licensed specifically for use with that application. Domino cannot use these drivers. If you try to use these drivers, a message appears stating that you must have a license. You may be given a phone number or other information. For more information about ODBC, see the Microsoft ODBC 2.0 Programmers Reference and SDK Guide published by Microsoft Press.

Registering data sources for ODBC


Before your Designer application can access data in a relational database, you must register a data source that tells the ODBC driver manager how to locate the data. Registering a data source ties a specific ODBC driver with the data to be accessed. The registration information includes the data you want to access, its associated server or directory, the back-end DBMS, and the network platform. To register this information in a registration file (ODBC.INI in Windows 95), you use the Windows Control Panel, a utility, such as the Windows ODBC Administrator Utility, or a script or formula. Note Users of existing DataLens programs that use Windows 3.1 must ensure that the data sources named in those programs are registered in ODBC.INI (not DATALENS.INI). To register a data source for ODBC You can use the operating system to register a data source for ODBC. Using the operating system allows you to register the data source hardware, software, and database type. The following procedure applies to Windows: 1. Open the Windows Control Panel. 2. Click the ODBC icon. 3. Click Add. 4. Select the driver you want, and click OK. 5. Enter the data source name, description, and requested information. 6. Some drivers require additional information; enter any other information necessary and click OK. 7. Click Close.

Chapter 16: Connecting to Enterprise Data 429

Writing formulas and scripts to access relational databases


The following @functions access an external database through ODBC and return a value or list of values: @DbColumn returns all the values in one column of a table, or all the distinct values. @DbLookup returns selected values in one column of a table by matching keys. @DbCommand passes a command to an external DBMS and returns the result. @DbColumn and @DbLookup can only retrieve data. They cant add, delete, or modify data, or perform other operations. @DbCommand can retrieve data or send other SQL statements that can change data. LotusScript provides a wider range of capabilities including the ability to update the external database. For more information about accessing external databases through ODBC and the ODBC versions of @DbColumn, @DbLookup, and @DbCommand, see the Programming Guide. The LotusScript Data Object (LS:DO) This LSX-compliant module allows you to use LotusScript to write applications that incorporate data from external non-Notes data sources. Your script may perform the following steps: Establish a connection with the data source. Each connection requires the data source name. If the data source name is not already registered, you must also provide additional information. Use SQL statements to send queries or other actions to the data source. Retrieve and use result sets. Read, modify, or add information into relational databases. Disconnect from the data source. For more information on writing scripts to access external databases, see the Programming Guide.

430 Application Development with Domino Designer

Chapter 17 Including Java Servlets in Web Applications


This chapter describes creating and running Java servlets on a Domino Web server. Servlets are invoked by URLs and are capable of performing a wide variety of custom operations for a Web application.

Overview of Java servlets


A servlet is a Java program that is run by the Domino Web server in response to a browser request. Servlets provide a convenient way to add powerful functionality to your Web application. In some ways, servlets act like CGI programs, but they are more tightly integrated with the server and can take advantage of special Java classes. For example, a servlet may connect to a relational database or enterprise system and get data in response to a Web browser request. Domino supports both Java servlets and Java applets for Web applications. The most important difference between these types of Java programs is how they are run. Servlets are server-side programs; a servlets Java class is loaded and run entirely within the Domino server and the result from the servlet, usually a page of HTML, is returned to the browser. In contrast, applets are client-side programs; an applets Java class is downloaded to the browser and is run by the browser. Therefore, applets require Java support in the browser, but servlets do not. Servlets for Domino must conform to the Java Servlet API Specification, an open standard published by Sun Microsystems, Inc. Running a servlet in Domino involves writing the servlet, enabling servlet support in Domino, and, if necessary, setting servlet properties.

431

Comparing agents, servlets, and CGI programs


Agents, servlets, and CGI programs all allow you to extend the functionality of your Domino Web application. Agents can be tightly integrated with a Web application through the form WebQueryOpen and WebQuerySave events. Servlets have special features available through the Servlet API classes, such as session and cookie management. Due to the growing popularity of Java, the trend today is to use servlets rather than CGI programs for new development. However, there is a large selection of off-the-shelf CGI programs already available. If you are writing your own application and need to program some functionality on the server, you may have a choice of which type of program to use. Each type of program has its advantages and will be the best choice in particular situations. Here are some suggested uses for each type of program:
Program type Agent Best uses Programs that perform Domino actions when documents are read or posted. Programs that need to be run on a schedule or when database actions occur, such as the arrival of new mail. Servlet Programs that use standard Java interfaces such as JDBC. Programs that use HTTP session maintenance or cookies. Complex or resource-intensive Java programs. CGI program Programs that need low-level access to system resources. Programs that interface with another product through a non-Java API.

Here are some useful comparisons of the properties of these programs.

What language can the program be written in?


Agent: Java, LotusScript, or Notes formula language. All are inherently cross-platform. Servlet: Java. Inherently cross-platform. CGI program: Platform scripting languages; that is, any language compiled into an executable file, or cross-platform languages such as Java or Perl.

432 Application Development with Domino Designer

Where is the program stored?


Agent: Stored in a Domino database, which means that agents take advantage of database replication and server clustering. Servlet: Stored in the file system, usually in the domino\servlet directory. CGI program: Stored in the file system, usually in the domino\cgi-bin directory.

How is the program invoked by a Web user?


Agent: Invoked automatically by a WebQueryOpen or WebQuerySave event, or invoked directly by an OpenAgent URL, for example, http://acme.com/sales.nsf/results?OpenAgent. Agents can also be triggered by server events, such as the arrival of new mail, or on a scheduled basis. Servlet: Invoked directly by a URL. Domino recognizes two types of servlet URLs. The first type specifies the servlet by its name, for example: http://acme.com/servlet/SQLDatabaseQuery?month=june. The second type specifies a file extension that the Domino administrator has mapped to a servlet, for example, http://acme.com/sqlquery.esp?month=june. CGI program: Invoked directly by a URL, for example, http://acme.com/cgi-bin/filesearch?string=widget.

When is the program loaded and unloaded by the server?


Agent: Loaded every time it is invoked and unloaded when it has finished. Servlet: Loaded once; stays loaded until the HTTP server task is shut down or restarted. This gives servlets a significant performance advantage over agents or CGI programs. However, this also means that the servlet classes can be accessed from many requests simultaneously, so you must make sure that the servlet code is thread-safe. CGI program: Loaded every time it is invoked and unloaded when it has finished.

Chapter 17: Including Java Servlets in Web Applications 433

How can the program interact with Domino?


Agent: LotusScript and Java agents can use the Domino object classes. Formula agents can use most @functions. Servlet: Can access Domino through the Common Object Request Broker (CORBA) interface. CGI program: Can access Domino through the CORBA interface, or through the Domino C or C++ APIs.

What security is available for the program?


Agent: To invoke an agent, a Web user must have at least Depositor access to the database containing the agent. An agent can run with the identity of its creator or the user. The full range of Domino security features applies to operations performed by the agent. Servlet: Access to the servlet can be controlled by file-protection documents in the Domino Directory. If the servlet accesses Domino through the CORBA interface, it can specify a Domino user name and Internet password. Domino security applies to all COBRA operations. CGI program: Access to the program can be controlled by file-protection documents in the Domino Directory. If the program accesses Domino through a C API, it takes the identity of the server ID; if it uses the CORBA interface, it can specify a user name and Internet password. In both cases, Domino security applies.

Running servlets in Domino


Writing the servlet
To write a servlet, you need a Java compiler and the servlet API. You can obtain both from Sun Microsystems web site at http://java.sun.com. Download the Java Development Kit (JDK), which includes the compiler and other basic tools, and the Java Servlet Development Kit (JSDK), which includes the servlet API specification, the servlet .JAR file (jsdk.jar), and example servlets. The Sun site also provides links to other servlet resources on the Web. You can also write servlets using any popular Java development environment. As a convenience, a copy of jsdk.jar is included in the Domino server and Designer installation kits. It is identical to the file supplied in Suns JSDK. Sun periodically updates the JDK and JSDK. Domino 5.0 supports JDK 1.1.6 and JSDK 2.0. Domino quarterly maintenance releases (QMRs) often

434 Application Development with Domino Designer

incorporate Suns upgrades, so you should check the QMR Release Notes to verify the supported JDK and JSDK versions.

Enabling servlet support in Domino


Servlets are loaded and called by the Domino Java Servlet Manager, a part of the HTTP server task. The runtime Java support for servlets is provided by the Domino Java Virtual Machine (JVM). When the HTTP task is started, it can automatically start the servlet manager and load the JVM. The HTTP task will write status messages for these operations to the server console and log file. The servlet manager is controlled by settings in the Domino Directory Server document. The settings are located on the Internet Protocols Domino Web Engine tab of the Server document. The settings are as follows:
Setting Java servlet support Options None: (default) The HTTP task does not load the servlet manager or the JVM. Domino Servlet Manager: The HTTP task loads both the JVM and the servlet manager. Third Party Servlet Support: The HTTP task loads the JVM, but not the Domino servlet manager. This allows the use of third-party servlet managers such as IBMs WebSphere Application Server. Servlet URL path Class path The path in a URL that signals Domino that the URL refers to a servlet. The default is /servlet. A list of one or more paths which the Servlet Manager class loader will search to find servlets and their dependent classes. This setting allows you to add additional paths. You may specify directories, JAR files, and ZIP files. Paths may be absolute or relative to the Domino data directory. The default is domino\servlet. Examples: Relative directory path: domino\servlet Absolute directory path: c:\apps\MyServlets JAR file: c:\javamail\mail.jar ZIP file: domino\servlet\sql.zip Servlet file extensions A list of URL file extensions that signal Domino that a URL refers to a servlet. Each extension in the list must be mapped to a single servlet by a directive in the servlets.properties file. The default is no extensions.

Chapter 17: Including Java Servlets in Web Applications 435

The following settings control the Domino Servlet Managers runtime support of the Java Servlet API HttpSession interface. A servlet that does not use this interface is not affected by these settings. Note The HttpSession interface support is completely separate from the HTTP session authentication feature in Domino.
Setting Options Session state tracking Enabled: (default) The servlet manager periodically checks the user activity of all HttpSession instances. Sessions that have been idle for a given period of time are automatically terminated. The servlet manager calls the instances HttpSession.invalidate() method to inform the servlet that the session is being terminated. Disabled: Sessions will not be checked for inactivity. Idle session timeout Maximum active sessions Session persistence The number of minutes of user inactivity to wait before terminating a session. The default is 30 minutes. The number of simultaneous active sessions allowed. The default is 1,000 sessions. When this limit is reached, the sessions that have been idle the longest are terminated. Enabled: When the HTTP task exits, the servlet manager saves session data to a disk file called sessdata.ser in the Domino data directory. The session data will be reloaded when the HTTP task is restarted. Objects that the servlet has bound to sessions will also be saved if the objects implement the java.io.Serializable interface. Disabled: (default) All session data is discarded when the HTTP task exits.

Loading servlet classes with the JVM loader


The Servlet Manager class loader will not load classes that use native code, create custom class loaders, or perform certain other restricted operations. If your servlet requires a class that cant be loaded by the Servlet Manager, you can try loading it with the Domino JVM class loader. The JVM loader is normally responsible for loading classes from the standard Java archives installed with Domino, in particular the java.* and lotus.* packages. You can force a servlet to be loaded by the JVM loader rather than by the Servlet Manager loader by moving the servlet from the Servlet Manager classpath to the JVM classpath. The JVM classpath is specified by the NOTES.INI variable JavaUserClasses.

436 Application Development with Domino Designer

Setting properties for servlets


Special properties for individual servlets can be specified in a text file called servlets.properties located in the Domino data directory. The following properties can be specified: Alias Initialization arguments URL extension mapping Load at Servlet Manager startup These properties are specified by directives in the servlets.properties file. The general syntax of a directive is:
servlet(s).<name>.<property>=<value(s)>

Directives are case-sensitive. The servlets.properties file can also contain blank lines and comment lines starting with the # character. The servlets.properties file is optional. The default properties for servlets are: no alias, no initialization arguments, no extension mapping, and load servlets on demand.

Servlet aliases
The alias directive has this syntax:
servlet.<alias-name>.code=<class-name>

For example:
servlet.SQLQuery.code=sql.database.query.Servlet

A servlet alias is a convenient name by which to reference the servlet in a URL, instead of using its class name. An alias is especially useful if the servlet is in a package. The above example allows the servlet to be invoked by a URL like http://acme.com/servlet/SQLQuery?month=june rather than http://acme.com/servlet/sql.database.query.Servlet?month=june. You can assign more than one alias to a servlet. The servlet manager will create a new instance of the servlet on receiving the first URL that refers to each alias. The servlet manager will call the servlets init() method when a new instance is created. Since the alias name can be used in other directives in the properties file, the instances can be given different properties. For example, you could specify a separate initialization argument directive for each alias. Also, because the servlet classes are only loaded once even if multiple instances are created, the instances of the servlet can share data by using static class variables.

Chapter 17: Including Java Servlets in Web Applications 437

As a security feature, if you give a servlet an alias, the servlet cannot be directly referenced in a URL by its class name. This allows you to hide the actual name of a servlet.

Initialization arguments
You can specify initial data for a servlet in the properties file. The servlet can access the data by using the method ServletConfig.getInitParameter. The initialization directive has this syntax:
servlet.<alias or class name>.initArgs=<name1=value1>,<name2=value2>,...

Multiple arguments can be specified, separated by commas. For example:


servlet.SQLQuery.initArgs=target=db2,user=Domino,cacheSize=30

URL extension mapping


The URL extension mapping directive has this syntax:
servlet.<alias or class name>.extension=<extension> <extension> ...

You can assign more than one extension to a servlet, separating each from the next by a space. All extensions must also be included in the Servlet file extensions setting in the Server record. For example, to cause Domino to call the SQLQuery servlet whenever a URL specifies the extension sql or sq, add sql,sq to the server setting and add this directive to the properties file:
servlet.SQLQuery.extension=sql sq

This allows a user to invoke the servlet with a URL like this:
http://acme.com/query.sql?month=june

Load on startup
By default, the servlet manager loads a servlets class files into memory the first time a URL is received that refers to the servlet. However, you can specify that one or more servlets should be loaded immediately when the servlet manager is started. This prevents users from experiencing delays when servlets are first requested from URLs. The startup directive has this syntax:
servlets.startup=<alias or class> <alias or class> ...

Note that servlets is plural and that the servlet names must be separated by spaces.

438 Application Development with Domino Designer

If you have given a servlet one or more aliases, you can include the aliases in the startup directive. This will cause the servlet manager to load the servlet classes and then create an instance for each alias. After the servlet manager loads a servlets classes, they stay in memory until the Domino HTTP task is stopped by the console command tell http quit or restarted by the console command tell http restart. Before unloading a servlet, the servlet manager calls the destroy() method for each instance of the servlet, to give it a chance to clean up resources. A class that has been loaded by the JVM class loader remains loaded until the HTTP task is stopped. The tell http restart command will not unload the class. Example properties file Here is an example of a servlets.properties file:
# Properties for the sql servlet servlet.SQLQuery.code=sql.database.query.Servlet servlet.SQLQuery.initArgs=cache=30 servlet.SQLQuery.extension=sql # Properties for the mail servlet servlet.MailServlet.initArgs=mime=enabled,smime=disabled # Both servlets should be loaded at startup servlets.startup=SQLQuery MailServlet # end of file Example: Java servlet

This example servlet returns an HTML page that displays all the HTTP headers that the browser sent with the servlet request.
import import import import java.util.*; java.io.*; javax.servlet.*; javax.servlet.http.*;

public class ExampleServlet extends HttpServlet { public void doGet (HttpServletRequest request, HttpServletResponse 3response) throws IOException { response.setContentType("text/html"); ServletOutputStream out = response.getOutputStream(); out.println("<HTML><B>Headers sent with the request:</B><BR>"); for (Enumeration headers = request.getHeaderNames(); Chapter 17: Including Java Servlets in Web Applications 439

headers.hasMoreElements();) { String headerName = (String) headers.nextElement(); out.println("<BR>" + headerName + ": " + request.getHeader(headerName)); } } // end of method } // end of class

After you compile this code, copy the ExampleServlet.class file to your server domino\servlet directory. It does not need any special properties, so you do not need to create a servlets.properties file. Run the servlet from a browser by entering this URL, using the name of your server:
http://www.yourserver.com/servlet/ExampleServlet

The information in the page returned by the servlet depends on the browser. Here is the HTML page returned for a Netscape browser:
<HTML><B>Headers received with the request:</B><BR> <BR>ACCEPT-LANGUAGE: en <BR>CONNECTION: Keep-Alive <BR>ACCEPT: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */* <BR>USER-AGENT: Mozilla/4.05 [en] (Win95; U ;Nav) <BR>ACCEPT-CHARSET: iso-8859-1,*,utf-8 <BR>HOST: test1

440 Application Development with Domino Designer

Appendix A Domino Designer Templates


This appendix lists templates available with Domino Designer that are specifically intended for use by application developers. For information on system administration templates, see Application and System Templates in Administering the Domino System or Domino Administration Help.

Table of Domino Designer templates


If you install the templates with Domino Designer, youll find them in the Notes program directory.
Database title Discussion Notes & Web (R5.0) File name and design template name discsw50.ntf StdR50Disc Audience General Notes users and Web browser users Description Electronic conference room. Features: Threaded discussion with built-in user profiles that allow automatic mailing of links to items of interest. Anonymous responses, archiving, and public/private threads. Multiple navigators, alternate view templates, and hotspot actions for Web browser users. Document storage. Features: Review workflow (serial and parallel) and archiving. continued

Document Library - Notes & Web (R5.0)

doclbw50.ntf StdR50WebDocLib

General Notes users and Web browser users

441

Database title

File name and design template name

Audience General Notes users

Description Special version of the Document Library template dedicated to this application suite. Automatically loads and sizes the OLE object to the window; and stores and supports review cycles of documents created with suite products.

Microsoft Office doclbm50.ntf Library (R5.0) StdR50DocLibMS

Personal Journal (R4)

journal4.ntf StdR4Journal

General Notes users

Electronic diary where users can write and organize private ideas and documents. Includes instructions for customizing the design. A sample showing how to register Web users for Domino-based applications. Users can create accounts for themselves with no manual intervention. Model of team collaborative operations. Maintains several document communication types to represent meetings, discussions, and action items. Features parallel review processing, archiving, and newsletters.

Site Registration siregw50.ntf 5.0 StdSite50Reg

Web browser users

TeamRoom (R5.0)

teamrm50.ntf StdR50TeamRoom

General Notes users and Web browser users

For an in-depth look at features of several of these templates, see Domino Designer Templates Guide, available on the Notes.Net Web site (http://www.notes.net).

442 Application Development with Domino Designer

Appendix B Importing to and Exporting from Views


Importing data allows you to move data from an old system into a view. Exporting data allows you to create a table of the data in a view for use in a presentation or report.

File formats you can export and import


No matter what type of data you want to import into a view, its best to import a small test file first. You can quickly determine whether the import is working correctly and make any necessary corrections before you import the entire file. The following table lists the types of files you can import and export.
File type Lotus 1-2-3 and Symphony Microsoft Excel* Tabular text .tab, .txt, .prn, .rpt ASCII text arranged in rows and columns; limit of 1536 characters per record, total ASCII text that retains its structure in fields and values; shown as one record per page and one field per line; limit of 256 bytes per simple text field File extensions .wks, .wk1, .wrk**, .wr1**, .wk3, .wk4 File description Entire worksheet or named range

Structured text

.ltr, .cgn, .str

*To import a Microsoft Excel file, use Excel to save the file as a 1-2-3 worksheet and then import it. **You cannot import a .wrk or .wr1 file to a view, but you may export to either format. If you import a multiple-worksheet file, only the worksheet that was most recently viewed will be imported. If you import a specific range from a multiple-worksheet file, only the information from the most recently viewed worksheet will be imported.

443

Importing options
Formatting options
You have three choices for generating the column titles and widths when you import a file. Choose View Defined if the column names and column widths in the source worksheet are identical to the names and widths of the columns in the view. Choose WKS Title Defined if youve set up the worksheet so that the cells in the first row of the worksheet match the column headers and fields in the view. The cells in the first row must be labels. Choose Format File Defined if you are using a column descriptor file (.col) that contains column style instructions.

Including additional fields for imported documents


You can use the import option Calculate fields on form during document import if you want the newly created document to contain all of the fields of the form youre using for the import. Notes imports information faster when you do not select this option. If you first import without selecting this option and the results are not what you expect for example, fields that rely on other fields are empty or incorrect import the worksheet again and choose this option.

Guidelines
Notes uses a character translation file (.cls) to translate foreign symbols and characters. The .cls file must be in the Notes program directory.

Importing worksheets
Before you import a worksheet, you must create a form and a view to hold the imported data. When you import a worksheet into the view, each worksheet row becomes an individual document, and each worksheet column becomes a field. The original cell contents become the field contents. You can import data into either main documents or response documents. Notes doesnt wrap lines of an imported worksheet. If a worksheet has more columns than a window can display, use the horizontal scroll bars to see the full width of the worksheet. Notes can handle a worksheet whose maximum text width is 22.75 inches; additional text is not displayed in the columns.
444 Application Development with Domino Designer

Importing worksheet data into a view


The source file containing the worksheet must be on your local hard drive or on a file server to which you are connected. 1. Select the database and open the view that will receive the source data. 2. Choose File - Import. 3. Select the name of the source file. 4. Select 123 Worksheet. 5. Click Import. 6. Select a form to use for the imported source data from the Use Form list. 7. Leave Main Document(s) selected in the Import as list, unless you are creating response documents. 8. Select a Column format. 9. If you select Format File Defined, enter the name of the .col file, including the complete operating system path. 10. To import part of a worksheet, type a range name or range address in the WKS Range Name box. You cannot import a 3-D range. Note If you import a multiple-sheet worksheet file, Domino imports only the sheet that was open when the file was last closed, or, if importing a specified range, imports the range from that sheet. 11. (Optional) Select Calculate fields on form during document import. 12. Click OK. After importing, you can change the column font to a proportional space font, such as Courier, in the view design pane to improve the display of worksheet data.

Importing tabular text


Tabular text is ASCII text arranged in rows and columns, separated by characters. When you import a tabular text file into a view, each text row becomes an individual document, and each text column becomes a field. The original cell contents become field contents. There is a limit of 1536 total characters per record when importing tabular text into a view. If the ASCII file and the view have different formats, create a column descriptor file (.col) to parse the ASCII file so its individual components correspond to columns in the view or document fields. Then when you
Appendix B: Importing to and Exporting from Views 445

import the ASCII file, select the Use format file option in the Tabular Text Import dialog box.

Viewing imported text


ASCII text files are monospaced. If columns in the view use a proportional font, text from the imported file may be truncated. To avoid problems when importing text into a view, select Typewriter Fonts (monospaced text) for the columns. You may want to resize columns to be sure the data is not truncated on import. Truncation occurs only in the displayed text; no data is lost.

Importing tabular text into a view


The source file containing the tabular text file must be on your local hard drive or on a file server to which you are connected. 1. Select the database and open the view that will receive the source data. 2. Choose File - Import. 3. Select Tabular Text. 4. Select the name of the source file. 5. Click Import. 6. Select a form to use for the imported source data from the Use Form list. 7. (Optional) Enter a Header Line Count or a Footer Line Count. 8. Enter the number of Lines Per Page in the source file. 9. Leave Main Document(s) selected in the Import as list, unless you are creating response documents. 10. (Optional) Select Calculate fields on form during document import. 11. (Optional) Select Use format file, click Choose format file, and select a column descriptor (.col) file. 12. Click OK. Header Line Count; Footer Line Count To import only the data, specify the number of header and/or footer lines that you want Notes to ignore in the source file. Lines per Page The Lines per Page setting establishes how many lines of data each Notes document receives. The total number of lines in the imported documents are calculated as: Lines Per Page - (Header Line Count + Footer Line Count)

446 Application Development with Domino Designer

Importing structured text files


Structured text is ASCII text that retains its structure in fields and values. When you import a structured text file into a view, the field names in the text file must correspond to the field names in a Notes document in the view. To do this, create a form that contains the names of the fields youre importing.

Importing structured text into a view


The source file containing the structured text file must be on your local hard drive or on a file server to which you are connected. 1. Select the database and open the view that will receive the source data. 2. Choose File - Import. 3. Select Structured Text. 4. Select the name of the source file. 5. Click Import. 6. Select a form to use for the imported source data from the Use Form list. 7. Select an Inter-Document Delimiter to determine how to separate the records. Select Form-feed if the records in the source file are separated by a form feed (ASCII 12). Select Character Code if the records in the file are separated by a delimiter other than the default, ASCII (form-feed). 8. Leave Main Document(s) selected in the Import as list unless you are creating response documents. 9. Do one of the following: Select Justify in the For body text list to wrap text to fit the Notes window Select Preserve Line Breaks in the For body text list to maintain the existing line breaks in the source file and add a return character at the end of each line of text. 10. (Optional) Select Calculate fields on form during document import. 11. Click OK.

Appendix B: Importing to and Exporting from Views 447

Creating a column descriptor (.col) file


A column descriptor (.col) file is an ASCII text file that contains instructions for mapping each column in a source file into the fields and columns of a Notes view. .col files are for use only with tabular ASCII files and worksheet files. 1. Use any ASCII text editor to create a file with the extension .col. 2. Use the column descriptor keywords and syntax to describe how to import each column from the source file. 3. Write formulas in a section that is delimited by the keywords FORMULASTART and FORMULAEND. 4. Close and save the file.

Using a column descriptor file (.col) to map a source file to a Notes view
To import many files that have an identical structure into a view, create a column format descriptor (.col) file. A .col file is like a map that defines which data from the source file goes into which Notes field. A .col file is for use only with tabular text files and worksheet files. A .col file is an ASCII text file that contains a series of column definition statements, followed by a section containing formulas that control the contents of fields in the Notes view. You write one statement for each column in the source file. This statement describes how to format and map the columns in the source file to columns in the Notes view. For best results, use exactly the same field names in the .col file and in the Notes view.

Mapping a column to a field in a view


Enter the name of the column in the source file. The name should be identical to the name of the corresponding field in a form. After you enter the column name, you can provide an optional statement that specifies the data type of the data. You must, however, provide statements that define the format of the source data; that is, the delimiter or fixed position of the column. If you use field names in the .col file that are not in the Notes view, Notes imports the data for those fields, but the data wont appear in the form or view until you create Notes field names that exactly match those in the .col file. For example, if the .col file uses the field name Phone and the Notes view uses PhoneNumber, data for the Phone field is present in the view but is not displayed. To correct this problem, change the name of the existing Notes field to Phone, create a synonym for the existing field, or
448 Application Development with Domino Designer

create a new Notes field called Phone, and refer to the field in the view youre using.

Specifying the data type of a column


When you import a file, Notes automatically determines the datatype of each column, based on the appearance of the data. For example, if the column in the source file contains data in the form 7/19/97, Notes imports the data as dates. As part of a field definition, you can provide an optional TYPE expression, followed by the appropriate data type: Text, Number, or Datetime. For example, to import the contents of a field called DateOfBirth as a date, enter the following field definition into the .col file:
DateOfBirth: TYPE DATETIME

The data in the source column must fit the datatype you specify. If Notes encounters data that doesnt match the datatype you specify, Notes imports the data as the type it most resembles.

Guidelines
The formulas that you write in a .col file describe how to modify the incoming values for display in the view. These formulas, which follow the same rules as view selection formulas, may perform such operations as: Use @If formulas to test incoming values and display a specific value in the view, depending on the result of the formula Use text manipulation functions to modify the appearance of the incoming value; for example, to concatenate values or trim excess space characters from incoming values Enter default values in fields

Writing a .col file for a worksheet


To import worksheets using .col files, use these keywords: WKSCOL This keyword allows you to associate a field name with a specific worksheet column. The syntax for a statement using this keyword is: fieldname: WKSCOL columnletter

Appendix B: Importing to and Exporting from Views 449

Where: fieldname is the name of the field in the view. columnletter is the letter of the source column in the worksheet that maps to that field name. Only columns specified by the WKSCOL keyword will be imported. RANGE This keyword specifies the worksheet range to be imported. The syntax for a statement using this keyword is: RANGE rangename Where: rangename is the name of the range in the worksheet. The range must be a valid range name in the imported file. If you use a RANGE statement, the first WKSCOL statement in the .col file must refer to the first column in the range. For example, if the range starts at column D, the first WKSCOL statement in the .col file must be: Fieldname: WKSCOL D Note that a RANGE statement in a .col file overrides any range name entered in the Worksheet Import Settings box.

Writing a .col file for a tabular text file


Tabular text is ASCII text arranged in rows and columns, separated by space characters.

Specifying the delimiter of a column


If the tabular text file uses a delimiter character to separate columns of data, you must use the UNTIL keyword to specify the delimiter as part of each field definition. For example, if the source data is delimited by commas, as in: Smith, Robert, Gryphon Real Estate, 555-1212 and the view contains the following field names: LastName, FirstName, Company, Phone then the .col file will contain the following lines:
LastName: UNTIL ",";

450 Application Development with Domino Designer

FirstName: UNTIL ","; Company: UNTIL ","; Phone: UNTIL "";

If there is no delimiter at the end of the record (row), you identify the end of the last field as a null ().

Specifying the start, end, and width of a fixed-width column


If the tabular text file contains fixed-width columns of data, you use the START keyword along with either the END or WIDTH keyword to define each field. For example, if the source data contains a LastName field that is twelve characters wide and the view contains a field named LastName, the .col file must contain the following column definition:
LastName: START 01 END 13

or
LastName: Start 01 WIDTH 12

The first column position is always 01, not 0. The following lines of a .col file give two sets of instructions:
LastName: START 1 WIDTH 12 FirstName: TYPE TEXT START 13 END 20

The first line puts the contents of the first field, LastName, at position 1 and allows 12 characters for it. The second line specifies that the data type of the FirstName field is text, begins the contents of the field at position 13, and allows 8 characters for it.

Specifying the header, footer, and lines per page


The HEADER, FOOTER, and LINESPERPAGE keywords tell Notes to ignore headers and footers during importing. The number of lines in the imported document are calculated as: LinesPerPage - (HeaderLines + FooterLines) For example, the following line of a .col file tells Notes to ignore four heading lines and one footer line and sets the maximum number of lines per page to 66:
HEADERLINE 4 FOOTERLINE 1 LINESPERPAGE 66

The keywords may appear together or alone on a line in the file. These settings in a .col file override values in the Tabular Text Import dialog box.
Appendix B: Importing to and Exporting from Views 451

Writing formulas for .col files


All formulas in a .col file must appear after all the column definition statements. A .col file can have only one FORMULASTART and FORMULAEND sequence. FORMULASTART must appear alone on a line before the first formula. FORMULAEND must appear alone on a line after the last formula. Each line of formulas between these keywords must end with a semicolon. Example The following .col file is used to import a 1-2-3 .WK3 file that records a checkbook balance.
;COL file for checkbook worksheet ;Discovers checkbook errors Define five columns of input date: WKSCOL A chknum: WKSCOL B amount: WKSCOL C deposits: WKSCOL F withdrawals: WKSCOL G balance: WKSCOL K ;Define one column to mark bounced checks FORMULASTART FIELD bounced:=@IF(balance<0,"Yes"; "No"); FORMULAEND

In this example, columns D, E, H, I, and J in the worksheet are not imported into the view.

Exporting views
You can export a view to a worksheet, a tabular text file, or a structured text file.

Exporting to a worksheet
When you export a view to a worksheet, each document becomes a row in the worksheet. Each field becomes a column in the worksheet. The original field contents become cell contents. Column titles become labels in the worksheet.

452 Application Development with Domino Designer

When you export a view to a new worksheet file, Notes exports the file in 1-2-3 .wk1 format. Although you can specify any extension with the file name, its best to keep the extension .wl1. When you open the exported file in a newer release of 1-2-3, 1-2-3 automatically converts the file to its new format and adds the appropriate extension. If you change the exported file to .wk2, .wk3, or .wk4 before opening it in a release of 1-2-3 that uses that extension, then open the file in 1-2-3 and attempt to add and save attributes, the new copy of the file will be in conflict with the original, and you wont be able to save your changes. To export to a Microsoft Excel file, export the view as a 1-2-3 worksheet, and then save the file in 1-2-3 as a Microsoft Excel file.

Exporting to a tabular text file


When you export a view to a tabular text file, each document becomes a text row (line). Each field becomes a text column, separated by space characters. The original field contents become the cell contents. To see the separation between columns in the exported view, use a monospaced font for the columns in the original view. The result of a tabular export may not look exactly like the view. Views use a proportionally spaced font, but exports use a monospaced font. Export a few documents as a test. Then, if necessary, adjust the column width settings in the view before you perform the whole export. To display or edit the contents of a view in a Notes document, export the view to a tabular text file. Then import the tabular text file into a Notes document.

Exporting to a structured text file


Structured text is ASCII text that retains its structure in fields and values. Exporting a view to structured text creates a file containing the text of all the documents in the view, minus any rich text attributes. To export a view 1. Select the database and open the view you want to export. 2. (Optional) Select specific documents to export only a subset of the view. 3. Choose File - Export. 4. Select the file format youre exporting to.

Appendix B: Importing to and Exporting from Views 453

5. Do one of the following: To replace an existing file, select a directory and file name from the list. To create a new file, enter a new file name. To append to an existing tabular text file, select a directory and file name from the list. 6. Click Export. 7. If you selected an existing file, do one of the following: To replace the file, click Replace. To append to an existing file, click Append. 8. Click All documents unless you selected specific documents in Step 2. 9. (Optional, for 1-2-3 worksheet or tabular text formats) Select Include View titles to export the views column headings to a worksheet or tabular text file. 10. (Optional, for structured text format) Change the inter-document delimiter and word-wrap settings if you are exporting to a structured text file. 11. Click OK. Note In step 10, choose Form Feed to use a form-feed to separate records in the file, or choose Character Code to separate the records in the file with the ASCII code for a delimiter other than the default, ASCII 12 (form-feed), such as: 32 44 45 58 59 124 Space , : ; |

The word wrap option represents the number of characters at which each line wraps. The default is 75 characters.

454 Application Development with Domino Designer

Appendix C Developing Applications Using MAPI


This appendix describes the support available in Domino to access your Domino mail file and the Domino Directory.

Developing applications using MAPI


Domino Release 5.0 supports the messaging application program interface (MAPI), which allows mail integration between Domino and a MAPI-compliant messaging application, such as Microsoft Mail or Microsoft Exchange. The Domino MAPI service providers may be used by any extended or simple MAPI client. To support MAPI, Domino includes these service providers, which provide access from the Domino message, directory, and transport services to simple or extended MAPI clients: Address Book provider Message Store provider Message Transport provider Using the MAPI classes and methods supported by the Domino MAPI service providers, you can write C++ programs to integrate Domino with a MAPI-compliant mail system. A list of supported MAPI classes and methods appear at the end of this appendix.

The Address Book provider


The Address Book provider provides read-only access to the Domino Directories. Therefore, you cannot create individual or group entries in a Domino Directory. To specify that the provider search multiple Domino Directories when doing address lookups, set the NAMES= setting in the NOTES.INI file to include the file names of all of the Domino Directories to search. Also, add the names of the Domino Directories for Options - Addressing during Microsoft Exchange profile setup.
455

The Address Book provider searches the Domino Directory for recipients names according to the order specified in the profile. Any Simple or Extended MAPI client can use the Address Book provider to access a Domino mail file and Domino Directory.

The Message Store provider


The Message Store provider, which you can use as the default MAPI Message Store, is a tightly-coupled message store. That is, the Message Store provider, rather than the Message Transport provider, handles the delivery of messages when a recipient is a Notes user. Also, messages are sent using calls to the Message Store Message Interface rather than the MAPI Spooler. MAPI creates an Outbox folder the first time the Domino Message Store is accessed. The Outbox folder captures outgoing messages you send from any extended or simple MAPI client (for example, Microsoft Exchange or Office) when you are not connected to the LAN. Messages addressed to Notes recipients are stored in the Outbox folder and placed in the local mail.box database in Domino. Once a connection to the server is re-established, the messages are transferred. Messages addressed to non-Domino recipients are placed in the outgoing mail queue, the exchange.box database, and the MAPI Spooler handles them. The MAPI Folder Interface is mapped onto Domino folders. You can create, move, copy, rename, and delete folders. You can also create or delete file attachments in messages you compose while using the client application. Attachment data is set or obtained using the IStream or IStorage interfaces. RTF, message encryption, and message signing is supported. Complex restrictions, MAPI associated messages and folders, view definition, and arbitrary message sorting are not currently supported.

456 Application Development with Domino Designer

The Message Transport provider


The Domino Mailer and Router transfers messages between Notes users. When the MAPI spooler receives messages composed in a non-Notes message store, the Domino MAPI Message Transport provider registers Address and Message Types and sends messages to Notes recipients. If one or more recipients are not of ADDRTYPE Notes, the Mail Router passes the messages to the MAPI spooler.

MAPI recipient types


Domino MAPI service providers handle delivery of messages to the following recipient types: Users who access their Domino mail files through a simple or extended MAPI client, such as Microsoft Exchange Non-Notes users who access their non-Domino mail files through a simple or extended MAPI client, such as Microsoft Exchange Notes users who access their Domino mail files from the Notes desktop Users of foreign mail systems that use a gateway as a backend

Platforms and requirements for MAPI


Windows 95 When you install the Notes client, the Domino MAPI service providers are automatically installed. The required DLLs for the Windows messaging subsystem are already present in Windows 95. Windows NT 3.51 The Domino MAPI service providers are available for Windows NT 3.51. Since Windows NT 3.51 does not provide the Windows messaging subsystem, you must install the subsystem separately. Windows NT 4.0 The Domino MAPI service providers are available for Windows NT 4.0. The required DLLs for the Windows messaging subsystem are already present in Windows NT 4.0. Note The Domino MAPI service providers can be installed and used for node installations on all of these platforms.

Appendix C: Developing Applications Using MAPI 457

Mail The Domino MAPI service providers may only be used to access mail files that use the Domino Release 5.0 mail template (mail50.ntf). If you are upgrading from Release 4.x to Release 5.0, you must upgrade your mail file to use the mail template provided in Release 5.0. To use the service providers, both the client and the server must be running Release 5.0. The Profile Setup Wizard automatically installs all three service providers. When you create a Microsoft Exchange Profile, the wizard uses information stored in the current Location document in Domino. You make modifications to the Office (Network) Location document to configure the location for server-based mail. To use workstation-based mail, you modify the Travel or Island (Disconnected) Location document appropriately. Note that the Location type in the document must be either Local Area Network or No Connection. The Mail section of the location document must specify information about the mail file location, the name of the mail file, and the domain. Note During logon to the service providers, the settings for MDB_NO_DIALOG and AB_NO_DIALOG flags are ignored. As a result, the user is always prompted for a password. Address Book template To access Domino Directories through the Address Book Provider, you must apply the Domino Release 5.0 Domino Directory template (pubnames.ntf) to the design. If you are using workstation-based mail, apply the Personal Address Book template (pernames.ntf) to the design of the Personal Address Books.

458 Application Development with Domino Designer

MAPI classes and methods


MAPI classes CLASS IMAPIContainer Supported methods GetContentsTable GetHierarchyTable OpenEntry GetSearchCriteria Advise CompareEntryIDs GetLastError Logoff OpenEntry Unadvise Logon Shutdown Activate GetLastError GetState CopyMessages CreateFolder CreateMessage DeleteFolder DeleteMessages EmptyFolder GetMessageStatus SaveContentsSort SetMessageStatus CopyTo GetIDsFromNames GetLastError GetPropList GetProps OpenProperty SaveChanges SetProps DeleteProps continued

CLASS IABLogon

CLASS IABProvider CLASS IMAPIControl

CLASS IMAPIFolder

CLASS IMAPIProp

Appendix C: Developing Applications Using MAPI 459

MAPI classes CLASS IMAPITable

Supported methods Abort Advise CreateBookmark FindRow FreeBookmark GetLastError GetRowCount GetStatus QueryColumns QueryPosition QuerySortOrder Restrict (supported for Address Book Provider, but not for Message Store Provider) SeekRow SeekRowApprox SetColumns Unadvise CreateAttach DeleteAttach GetAttachmentTable GetRecipientTable ModifyRecipients OpenAttach SetReadFlag SubmitMessage Note Message object based on Notes note, not MAPI-supplied IMSG.DLL OLE Docfile representation. AbortSubmit Advise CompareEntryIDs FinishedMsg GetOutgoingQueue GetReceiveFolder NotifyNewMail OpenEntry SetLockState SetReceiveFolder StoreLogoff Unadvise continued

CLASS IMessage

CLASS IMsgStore

460 Application Development with Domino Designer

MAPI classes CLASS IMSLogon

Supported methods Advise CompareEntryIDs GetLastError Logoff OpenEntry Unadvise CompareStoreIDs Logon Shutdown SpoolerLogon AddressTypes EndMessage FlushQueues Idle (supported, but not used for tightly-coupled message store) OpenStatusEntry Poll (supported, but not used for tightly-coupled message store) RegisterOptions StartMessage (supported, but not used for tightly-coupled message store) SubmitMessage TransportNotify Shutdown TransportLogon All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class All methods supported for this class

CLASS IMSProvider

CLASS IXPLogon

CLASS IXPProvider CLASS IMailUser CLASS IAttach CLASS IMAPIAdviseSink CLASS IMAPIProfile CLASS IMAPIContainer CLASS IMAPIStatus CLASS IPropData CLASS ITableData

Appendix C: Developing Applications Using MAPI 461

Appendix D Features to Avoid Using in Web Applications


The majority of design features are available for both Domino and Web users. This appendix describes the features that arent applicable to Web browsers or arent yet supported for them.

Domino @functions that are not supported on the Web


The following groups of @functions are not supported in Web applications or are supported differently than they are in Domino applications.
@Function @Certificate @DbCommand Available only with the syntax @DbCommand(Domino;ViewNextPage) and @DbCommand (Domino;ViewPreviousPage) to create a link to the next/previous page in a view. Not available in other contexts. Comments

@DDEExecute @DDEInitiate @DDEPoke @DDETerminate @DocMark @DeleteDocument @DocChildren @DocDescendants @DocLevel @DocNumber @DocParentNumber @DocSiblings @IsCategory @IsExpandable @Responses continued Not available except in column formulas.

463

@Function @DialogBox @PickList @Prompt @IsModalHelp @GetPortsList @Environment @SetEnvironment ENVIRONMENT keyword @MailSend @Domain @MailDbName @MailEncryptSavedPreference @MailEncryptSendPreference @MailSavePreference @MailSignPreference @IsAgentEnabled @IsDocBeingMailed @URLGetHeader @URLHistory @UserPrivileges @Platform for users platform.

Comments

Use predefined field names to gather information about the Web users environment by requesting Common Gateway Interface (CGI) environment variables.

Returns servers platform only. Use @ClientType to distinguish between Web and Domino users.

Domino actions and agent properties that are not supported on the Web
Avoid using the following actions and agent features in a Web application.
Feature Agents Manually From Actions Menu Web users do not have an Actions menu. Run agents with actions or buttons that use @Command([ToolsRunMacro]) or through the WebQuerySave and WebQueryOpen form events. The concepts of pasted documents and selected documents dont apply to Web applications. continued Comments

If Documents Have Been Pasted and the document selection option Selected documents

464 Application Development with Domino Designer

Feature Form and view actions Include action in Action menu

Comments Web users do not have an Actions menu. Use the option Include action in button bar instead. Use supported @commands to create the equivalent actions.

Default form and view actions that use system commands (such as *Edit Document, *Categorize) Programs for actions and agents Simple actions LotusScript for forms, actions, and buttons Alias a folder simple action

Supported for agents only. Dragging and dropping to folders is not available on the Web.

Domino calendar features that are not supported on the Web


Avoid using these calendar features in a Web application.
Feature Embedded Group Scheduler Calendar pop-up controls Date Picker Time control Duration control Comments

Domino field properties that are not supported on the Web


Avoid using the following field features in a Web application.
Feature Notes/FX fields Field Info properties Compute after Validation Give this field default focus Control properties Options Display entry helper button is not supported. continued Appendix D: Features to Avoid Using in Web Applications 465 Comments

Feature Advanced properties Help description Enable encryption for this field Sign if mailed or saved in section Names fields Control properties Choices (for Names fields)

Comments

Web users cannot read data in encrypted fields.

Use Address dialog for choices, Use Access Control List for choices, and Use View dialog for choices are not supported. Web user access to databases is based on the authenticated name. For some browsers, the order of the data returned from multiple selections in a checkbox may be different from the selection order. The data itself remains the same, but the order returned is different.

Checkbox fields Checkbox selection order

Domino form properties that are not supported on the Web


Avoid using the following form features in a Web application.
Feature Form Info properties Versioning Anonymous forms Merge replication conflicts Store form in document - edit mode Read mode is supported, but do not use for documents that need to be created or edited on the Web. Disable field exchange Automatically refresh fields continued Comments

466 Application Development with Domino Designer

Feature Default properties

Comments

On Create: Inherit entire selected Inheritance from selected documents is document into rich text field as supported on the Web, but only if the field is Link and as Collapsible rich text of type text, the document resides in the same This applies to rich text fields only. database, and the database property, Web Access: Use JavaScript when generating On Create may be used for text pages is selected. fields on the Web. Inherit entire selected document into rich text field as rich text is supported. On Open: Show context pane Security properties Default encryption keys Disable printing/ forwarding/copying to clipboard Form elements Layout regions Pop-up hotspots ActiveX components, OLE, and OCX objects Not supported on Macintosh, UNIX, and OS/2 platforms. Supported for display on Windows NT and Windows 95 platforms, but users cant save changes made to objects. If the top left cell of a table has a border, the entire table is displayed with a border; otherwise, there is no border because of limitations with HTML. Use tables to align form components instead. Not applicable to Web.

Border controls for tables

Domino formatting features that are not supported on the Web


Avoid using the following formatting features in Web applications.
Feature Bullet character in an ordered list (sizing and color) International characters Comments The color and size of a bullet in an ordered list cannot be manipulated on the Web. The international characters that are supported on the Web vary depending on the browser version and the fonts installed on the platform used to view and edit text on the Web. continued Appendix D: Features to Avoid Using in Web Applications 467

Feature First-line indent or outdent in a paragraph Full justification paragraph alignment Images Ordered lists

Comments

Avoid this feature if editing a document with both the Notes client and the editor applet. Avoid this feature if the list will be edited in the Notes client and the editor applet. Ordered lists are supported if they are edited with the editor applet only. There are limitations for pasting text in the editor applet. See Designing Fields for information about using the editor applet for editing rich text fields on the Web.

Pasting text

Tabs Tables Unordered lists Avoid this feature if editing a document with both the Notes client and the editor applet. Avoid this feature if the list will be edited in the Notes client. Unordered lists are supported if they are edited with the editor applet only.

Domino frame properties that are not supported on the Web


Avoid using this frame feature in a Web application.
Feature Basics properties Default target for links in frame Targets may be set in both the Frame properties box and the design element contained by that frame. The design element in this case may be a form, page, or view. If a target is set in the Frame properties box of a Web application, but not in the design element, and the design element is later replaced, the links in the frame will not go to the target specified in the Frame properties. This can be avoided by specifying the same target frame in both the Frame properties and the design element. Comments

468 Application Development with Domino Designer

Domino horizontal rule properties that are not supported on the Web
Avoid using the following horizontal rule feature in a Web application.
Feature Horizontal Rule Info properties Color Gradient is not supported on the Web. Comments

Domino hotspot properties that are not supported on the Web


Avoid using the following hotspot feature in a Web application.
Feature Hotspot Info properties Show border around hotspot Comments

Domino navigator properties that are not supported on the Web


Avoid using the following navigator features in a Web application.
Feature Navigators Info properties Auto adjust panes at runtime Objects Polyline objects HiLite properties Highlight when... options for navigator objects Polyline objects display on the Web, but clicking them has no effect. Comments

Appendix D: Features to Avoid Using in Web Applications 469

Domino table properties that are not supported on the Web


Avoid using the following table features in a Web application.
Feature Table Layout properties Column spacing This property is not supported in Web applications, but may affect the Width property of a cell, which is supported on the Web. Comments

Minimum height Row spacing Table Width Cell Borders properties Color Cell Border Style Cell Border Thickness Table/Cell Background properties Style Cell image Table Borders properties Border style Border color Border effects Thickness Table Margins properties Left Right Table wrap Compatibility Table Rows properties Show only one row at a time Switch rows every n milliseconds and transitions are not supported. Determined by individual cell borders. The table color is used. Width is not supported. Solid is the only color option supported on the Web. Gradients will appear as the first color. Cells are the same color as the table. The style options, Ridge and Groove, are not supported on the Web. Border thickness settings greater than 1 are not supported. Same as window is ignored in a Web application.

470 Application Development with Domino Designer

Domino text styles that are not supported on the Web


Avoid using the following text features in a Web application.
Feature Font properties Default fonts (Helvetica and Times Roman in Windows). Alignment and Tab properties Full Justification and No Wrap alignment styles Interline spacing A line spacing which is not a whole number will be rounded up to the nearest whole number. For example, a line spacing of 1.5 will be rounded up to 2. Comments

Formatting aids, such as tabs, HTML doesnt support these formatting indents, outdents, and extra spaces styles. Use tables to align form components. Use the text style Pass-Thru HTML to use HTML formatting styles. Text effects properties Shadow, Emboss, and Extrude text styles

Domino view properties that are not supported on the Web


Avoid using the following view and folder features in a Web application.
Feature Views and folders Folders Views Options properties Show in View menu Web applications do not have a View menu. To exclude a view from the folders navigator, use the Design - Design Properties box to hide the view from Web users, or include the view name in parentheses for example, (HiddenView). continued Private folders are not supported in outlines on the web. Private views are not supported. Comments

Appendix D: Features to Avoid Using in Web Applications 471

Feature On Open: Go To... options On Refresh options Style properties Unread rows Alternate rows Show selection margin Beveled headings Advanced properties Refresh index options Discard index options Columns Basics properties Show twistie when row is expandable

Comments

Views can be re-indexed at a Domino server.

Triangles are always shown.

View properties that are not supported by the Domino view applet
Avoid using the following Domino view applet features in a Web application.
Feature Pass-Thru HTML Horizontal scrollbars View View Info properties Calendar views Options properties On open: Go to last opened document On Refresh Style properties Unread rows color Alternate rows color continued 472 Application Development with Domino Designer None of these options are supported. Calendar views are not supported. The HTML Calendar view will be generated even if view applet is selected. Comments

Feature Beveled headings Lines per heading Shrink rows to content Row spacing Advanced properties Refresh index Discard index Unread marks For ODBC Access Active Link Unvisited Link Visited Link Restrict initial index build to designer or manager Column Font properties Title properties Font Advanced properties Show values in this column as links

Comments

The available fonts are limited to a subset of fonts supported by Java.

The available fonts are limited to a subset of fonts supported by Java.

Appendix D: Features to Avoid Using in Web Applications 473

Appendix E Programming a Web Site


This appendix contains information about programming related to Web applications, such as Domino URL commands, formulas, Java, JavaScript, Perl and CGI scripting, and Visual Basic script.

Domino URL Commands


A URL command combines a specific URL with a command that manipulates an item such as a document or view. Adding Domino URL commands as HTML in forms gives users shortcuts for navigating databases and performing other tasks quickly.

The Domino URL command syntax


Domino URL commands have the syntax: http://Host/DominoObject?Action&Arguments Where Host = a DNS entry or an IP address DominoObject = a Domino construct (For example, a database, view, document, form, navigator, agent, and so on.) URL commands for accessing DominoObjects use the following syntax: http://Host/Database/DominoObject?Action&Arguments where Database = the database in which the DominoObject resides. Action = the desired operation on the specified DominoObject (For example, ?OpenDatabase, ?OpenView, ?OpenDocument, ?EditDocument, ?OpenForm, and so on.) Arguments = a qualifier of the action. (For example, Count = 10 combined with the ?OpenView action limits the number of rows displayed in a view to 10.) Syntax Guidelines Domino URLs do not use the server name. Host identifies the server. The maximum size of a URL command is 1024 bytes.
475

Special identifiers used in Domino URL commands include: $defaultView, $defaultForm, $defaultNav, $searchForm, $file, $icon, $help, $about, and $first. DominoObject can be any of the following: for a database, the database name or replica ID; for other objects, the DominoObjects name, universal ID, NoteID, or special identifier. For example, to specify a view in a URL, you can use any of the following: the view name, view universal ID, view NoteID, or $defaultView. A Notes database should be specified by placing a double underscore before the replica ID and adding an .nsf suffix to the end. For example: __852562F3007ABFD6.nsf A DominoObjects name and universal ID are identical in all replicas of a database, but the DominoObjects NoteID will probably change in database replicas. Therefore, it is best to use the DominoObject name or universal ID in URLs. One name or alias can refer to two objects for example, two forms with the same name when one is hidden from Notes users and one is hidden from Web users. Action can be explicit or implicit. Examples of explicit actions include ?OpenServer, ?OpenDatabase, ?OpenView, ?OpenDocument, ?OpenForm, and ?EditDocument. Examples of implicit actions include ?Open, ?Edit, and ?Delete. If you do not specify an action, Domino defaults to the ?Open action. An action may also be preceded by an exclamation point (!). For example, ?OpenDocument could also be written as !OpenDocument. When Domino is running as an extension to Microsoft Internet Information Server, a database is required in the URL syntax for server commands such as ?OpenServer, ?Login, ?Logout, and ?Redirect. You may use the name of a database that does not exist in order to supply the correct sytnax without opening a database. For example: http://www.mercury.com/dummy.nsf?Login To require user authentication, append the Login argument to any Domino URL. Because URLs cannot contain spaces, use the + (plus sign) as a separator. For example: http://www.mercury.com/discussion.nsf/By+Author Where a name or argument contains a symbol that is not part of the URL syntax and would conflict with URL syntax, such as plus signs (+), slashes (\ or /), or ampersands (&), use %xx (where xx is the hex ascii value) as a separator. For example: http://www.mer%+maid.com/leads.nsf/By+Salesperson?Open View&ExpandView

476 Application Development with Domino Designer

Separate arguments with & (ampersand). For example: http://www.mercury.com/leads.nsf/By+Salesperson?Open View&ExpandView Separate hierarchical names with / (slash). For example, to open a view named Docs\By Author in a database named Discussion, enter: http://www.mercury.com/discussion.nsf/Docs/By+Author If you are generating your own URLs for any part of an application, use simple aliases whenever possible to avoid URLs with unsupported characters. Domino will convert URLs containing unsupported non-ascii characters to base32 encoding. URL commands may also refer to databases with .nsf4 or .box suffixes. They may also refer to template files (.ntf), but they may only be opened in preview mode. Selecting Web access: Use JavaScript when generating pages in Database properties will enable you to compute URLs attached to buttons and hotspots on the Click event. If this option is not selected, URLs attached to buttons and hotspots will be computed when the page is generated. This can be useful if youre using editable fields on a form.

URL commands for opening servers, databases, and views


The following commands access servers, databases, views, About This Database documents, Help documents, and database icons. Databases must be in the notes\data directory or a subdirectory of the notes\data directory in order to be accessed by a URL command, except in the case of server commands such as ?OpenServer, ?Login, ?Logout, and ?Redirect. You may use the name of a database that does not exist in the server command syntax if a database is required, as it is with Microsoft Internet Information Server. If the database referenced in a server command does not exist, it will be ignored. Use ?Redirect to redirect doclinks across servers. Hidden design elements are hidden from the server too; you cant use Domino URL commands to access documents in hidden views.

OpenServer
Syntax http://Host/?OpenServer http://Host/Dummy.nsf?OpenServer

Appendix E: Programming a Web Site 477

Example http://www.mercury.com/?OpenServer http://www.mercury.com?dummy.nsf?OpenServer

Redirect
Syntax http://Server/Dummy.nsf?Redirect&Name=notesserver&Id=To=encodedurl Where: http://Server refers to the Web server which is generating the URL. Name=notesserver specifies a Domino server name in its common or abbreviated form. This is optional when the By Database setting on the server is on. ID=repid indicates the replica ID of the database to be located. This is an optional argument. To=encodedurl specifies the rest of the URL. Example http://mercury.com/dummy.nsf?Redirect&Name=Mister%2FHankey&Id =0525666D0060ABBF&To=%FAView%3FOpenView

OpenDatabase
Syntax http://Host/DatabaseFileName?OpenDatabase http://Host/__DatabaseReplicaID.nsf?OpenDatabase Examples http://www.mercury.com/leads.nsf?OpenDatabase http://www.mercury.com/sales/discussion.nsf?OpenDatabase http://www.mercury.com/__852562F3007ABFD6.nsf/OpenDatabase

OpenView
Syntax http://Host/Database/ViewName?OpenView http://Host/Database/ViewUniversalID?OpenView http://Host/Database/ViewNoteID?OpenView http://Host/Database/$defaultview?OpenView

478 Application Development with Domino Designer

Examples http://www.mercury.com/leads.nsf/By+Salesperson?OpenView http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F300702264?OpenView http://www.mercury.com/leads.nsf/$defaultview?OpenView Optional arguments for OpenView Append optional arguments to refine the URL. Combine any of the following arguments for the desired result. Collapse = n Where: n is the row number to display in collapsed format in a hierarchical view. Do not combine this argument with the ExpandView or CollapseView arguments. CollapseView Displays the view in collapsed format Count = n Where: n is the number of rows to display Expand = n Where: n is the row number to display in expanded format in a hierarchical view. Do not combine this argument with the ExpandView or CollapseView arguments. ExpandView Displays the view in expanded format Start = n Where: n is the row number to start with when displaying the view. The row number in a hierarchical view can include sub indexes (for example, Start=3.5.1 means the view will start at the third main topic, sub-topic 5, document 1).

Appendix E: Programming a Web Site 479

StartKey = string Where: string is a key to a document in the view. The view displays at that document. Examples http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&CollapseView http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&ExpandView http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&Start=3&Count=15 http://www.mercury.com/leads.nsf/ DDC087A8ACE170F8852562F30070226400000196?Open View&StartKey=F

OpenAbout
Use the OpenAbout command to access the About This Database document. Syntax http://Host/Database/$about?OpenAbout Example http://www.mercury.com/leads.nsf/$about?OpenAbout

OpenHelp
Use the OpenHelp command to access the Using This Database document. Syntax http://Host/Database/$help?OpenHelp Example http://www.mercury.com/leads.nsf/$help?OpenHelp

480 Application Development with Domino Designer

OpenIcon
Use the OpenIcon command to access the database icon. Syntax http://Host/Database/$icon?OpenIcon Example http://www.mercury.com/leads.nsf/$icon?OpenIcon

URL commands for opening framesets


OpenFrameset
Syntax http://Host/Database/FramesetName?OpenFrameset http://Host/Database/FramesetUNID?OpenFrameset http://Host/Database/FramesetNoteID?OpenFrameset Examples http://www.mercury.com/discussion.nsf/main?OpenFrameset http://www.mercury.com/discussion.nsf/ 35AE8FBFA573336A852563D100741784?OpenFrameset

URL commands for opening agents, forms, and navigators


The following commands open agents, forms, and navigators in a database. Hidden design elements are hidden from the server too; you cant use Domino URL commands to access documents in hidden forms.

OpenAgent
Syntax http://Host/Database/AgentName?OpenAgent Examples http://www.mercury.com/sales/leads.nsf/ Process+New+Leads?OpenAgent Note Agents may only be referred to by name. The use of UNID and NoteID are not supported when referring to an agent.

Appendix E: Programming a Web Site 481

OpenForm
Syntax http://Host/Database/FormName?OpenForm http://Host/Database/FormUniversalID?OpenForm http://Host/Database/FormNoteID?OpenForm http://Host/Database/$defaultform?OpenForm Examples http://www.mercury.com/products.nsf/Product?OpenForm http://www.mercury.com/products.nsf/ 625E6111C597A11B852563DD00724CC2?OpenForm http://www.mercury.com/products.nsf/$defaultform?OpenForm Optional argument for OpenForm ParentUNID = UniqueIDNumber Where: UniqueIDNumber is document ID of the parent document, which is used in response forms or when the form property Formulas inherit values from selected document is selected. Syntax http://Host/Database/FormUniversalID?OpenForm&ParentUNID Example http://www.mercury.com/products.nsf/ 40aa91d55cle4c8285256363004dc9e0?Open Form&ParentUNID=6bc72a92613fd6bf852563de001f1a25

OpenNavigator
Syntax http://Host/Database/NavigatorName?OpenNavigator http://Host/Database/NavigatorUniversalID?OpenNavigator http://Host/Database/NavigatorNoteID?OpenNavigator http://Host/Database/$defaultNav?OpenNavigator $defaultNav opens the folders pane in a database.

482 Application Development with Domino Designer

Examples http://www.mercury.com/products.nsf/Main+Navigator?OpenNavigator http://www.mercury.com/products.nsf/ 7B5BC17C7DC9EB7E85256207004F8862?OpenNavigator http://www.mercury.com/products.nsf/$defaultNav?OpenNavigator

ReadForm
Use the ReadForm command to display a form without showing its editable fields. ReadForm is useful for displaying a form as a simple Web page. Syntax http://Host/Database/FormName?ReadForm http://Host/Database/FormUniversalID?ReadForm http://Host/Database/FormNoteID?ReadForm http://Host/Database/$defaultform?ReadForm Examples http://www.mercury.com/home.nsf/Welcome?ReadForm http://www.mercury.com/products.nsf/ 625E6111C597A11B852563DD00724CC2?ReadForm http://www.mercury.com/products.nsf/$defaultform?ReadForm

URL commands for creating, deleting, editing, opening, and saving documents
The following commands manipulate documents in a database. Hidden design elements are hidden from the server, too; you cant use Domino URL commands to access documents in hidden views.

CreateDocument
The CreateDocument command is used as the POST action of an HTML form. When the user submits a form, Domino obtains the data entered in the form and creates a document. Syntax http://Host/Database/Form?CreateDocument http://Host/Database/NoteID?CreateDocument http://Host/Database/FormName?CreateDocument

Appendix E: Programming a Web Site 483

Where: FormName is the name of the form being accessed. Examples http://www.mercury.com/products.nsf/ b9815a87b36a85d9852563df004a9533?CreateDocument http://www.mercury.com/products.nsf/basketballs?CreateDocument

DeleteDocument
Syntax http://Host/Database/View/Document?DeleteDocument Example http://www.mercury.com/products.nsf/By+Part+Number/ PC156?DeleteDocument

EditDocument
Syntax http://Host/Database/View/Document?EditDocument Example http://www.mercury.com/products.nsf/By+Part+Number/ PC156?EditDocument

OpenDocument
Syntax http://Host/Database/View/Document?OpenDocument Where: Document is any of the following: DocumentKey the contents of the first sorted column in the specified view. DocumentUniversalID DocumentNoteID $first the first document in the view Examples http://www.mercury.com/products.nsf/By+Part+Number/ PC156?OpenDocument http://www.mercury.com/leads.nsf/By+Rep/ 35AE8FBFA573336A852563D100741784?OpenDocument

484 Application Development with Domino Designer

SaveDocument
The SaveDocument command is used as the POST action of a document being edited. Domino updates the document with the new data entered in the form. Syntax http://Host/Database/View/Document?SaveDocument Example http://www.mercury.com/products.nsf/ a0cefa69d38ad9ed8525631b006582d0/ 4c95c7c6700160e2852563df0078cfeb?SaveDocument

URL commands for opening documents by key


The following commands allow you to open a document by using the key value of the first sorted column of a view, such as a document name, or to generate a URL to link to a document by key. Hidden design elements are hidden from the server too; you cant use Domino URL commands to access documents in hidden views, unless youve hidden the view by surrounding its name in parentheses, rather than using the Hide tab in the Properties box.

Using Domino URLs to access a document


To open a document by key, create a sorted view with the sort on the first key column. Then use a URL to open the document. Syntax http://Host/Database/View/DocumentName?OpenDocument Where: View is the name of the view. To access a document regardless of the view, specify the document by its universal ID and substitute a zero (0) for the view name. DocumentName is the string, or key, that appears in the first sorted or categorized column of the view. Use this syntax to open, edit, or delete documents and to open attached files. Domino returns the first document in the view whose column key exactly matches the DocumentName. There may be more than one matching document; Domino always returns the first match. The key must match completely for Domino to return the document. However, the match is not case-sensitive or accent-sensitive.

Appendix E: Programming a Web Site 485

Note that View can be a view Note ID, UNID, or view name. In addition, the implicit form of any of these commands will work when appropriate. For example, you can omit the OpenDocument argument in a URL command and the document will still open because the command is automatically interpreted as OpenDocument. (EditDocument and DeleteDocument must be explicit commands.) Examples http://www.mercury.com/register.nsf/Registered+Users/J ay+Street?OpenDocument http://www.mercury.com/register.nsf/0/ 466c5172561e1c5c852566c2005f6bbb?OpenDocument

Using @commands to link to a document


For information about using @commands in Web applications, see Appendix D.

Using Domino URLs to access attachments


When Domino saves a file attachment with a document, it generates a URL so it can retrieve the file later. An attachment generates a URL whose last component is the original file name. For example:
http://domino.lotus.com/domdown.nsf/ViewUNID/DocumentUNID/ $File/DOMINO.EXE

ViewUNID can indicate a ViewID or a ViewName. DocumentUNID can be a Note ID or a DocumentKey. This allows you to create URL links to attachments by supplying a view name and document key. By default, the browser uses the name specified in the URL to save the file.

URL commands for opening pages


The following command will open a Web page using its name, UNID, or Note ID.

OpenPage
Syntax http://Host/Database/PageName?OpenPage http://Host/Database/PageUNID?OpenPage http://Host/Database/PageNoteID?OpenPage

486 Application Development with Domino Designer

Examples http://www.mercury.com/discussion.nsf/products?OpenPage http://www.mercury.com/discussion.nsf/ 35AE8FBFA573336A852563D100741784?OpenPage Optional arguments for OpenPage and OpenDocument The following arguments will manipulate outline controls on pages and documents. The arguments for OpenPage and OpenDocument commands use the same syntax regardless of the command. CollapseOutline=n Where n = the triangle at the top level of the outline. It is possible to expand triangles in hierarchical order. For example, &CollapseOutline=2.1.3 will collapse the second triangle at the top level of the outline, the first triangle at the second level, and the third triangle at the third level. Syntax http://Host/Database/PageName?OpenPage&CollapseOutline=n http://Host/Database/PageUNID?OpenPage&CollapseOutline=n http://Host/Database/PageNoteID?OpenPage&CollapseOutline=n Examples http://www.mercury.com/sales.nsf/products?OpenPage&Collapse Outline=1 http://www.mercury.com/sales.nsf/products?OpenDocument&Collapse Outline=1 http://www.mercury.com/sales.nsf/products?OpenPage&Collapse Outline=1.2.3 http://www.mercury.com/sales.nsf/products?OpenDocument&Collapse Outline=1.2.3 ExpandOutline=n Where n = the triangle at the first level of the outline. It is possible to expand a triangle in hierarchical order. For example, &ExpandOutline=2.1.3 will expand the second triangle at the top level of the outline, the first triangle at the second level, and the third triangle at the third level. Syntax http://Host/Database/PageName?OpenPage&ExpandOutline=n http://Host/Database/PageUNID?OpenPage&ExpandOutline=n http://Host/Database/PageNoteID?OpenPage&ExpandOutline=n
Appendix E: Programming a Web Site 487

Examples http://www.mercury.com/sales.nsf/products?OpenPage&Expand Outline=5 http://www.mercury.com/sales.nsf/products?OpenDocument&Expand Outline=5 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenPage&ExpandOutline=5.1.2 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenDocument&ExpandOutline= 5.1.2 StartOutline=n Where n = the triangle at the top level of the outline. It is possible to expand a triangle in hierarchical order. For example, &StartOutline=2.1.3 will start the display with the third triangle at the third level of the outline. Syntax http://Host/Database/PageName?OpenPage&StartOutline=n http://Host/Database/PageUNID?OpenPage&StartOutline=n http://Host/Database/PageNoteID?OpenPage&StartOutline=n Examples http://www.mercury.com/sales.nsf/products?OpenPage&StartOutline=1 http://www.mercury.com/sales.nsf/products?OpenDocument&Start Outline=1 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenPage&StartOutline=5.1.2 http://www.mercury.com/sales.nsf/ 35AE8FBFA573336A852563D100741784?OpenDocument&Start Outline=5.1.2

488 Application Development with Domino Designer

URL commands for opening attachments, image files, and OLE objects
The following commands open files and objects within a document.

OpenElement
Use the ?OpenElement command to access attachments, image files, and OLE objects. Using OpenElement with attachments Syntax http://Host/Database/View/Document/$File/Filename?OpenElement Example http:/ /www.mercury.com/lproducts.nsf/By+Part+Number/SN156/$File/ spec.txt?OpenElement Note If more than one attached file has the same name, the URL includes both the internal file name as well as the external name. Since the internal file name is not easily determined, make sure all attached files have unique names. Because some browsers require that the URL end with the attached file name, Domino treats all file attachment OpenElement commands as implicit commands. For example: http://Host/Database/View/Document/$File/InternalFileName/ Filename?OpenElement Using OpenElement with image files Syntax http://Host/Database/View/Document/FieldName/FieldOffset?OpenElement http://Host/Database/View/Document/FieldName/FieldOffset?Open Element&FieldElemFormat=ImageFormat Optional argument for OpenElement FieldElemFormat = ImageFormat Where: ImageFormat is either gif or jpeg. If you do not specify FieldElemFormat, Domino assumes the image file format is gif.

Appendix E: Programming a Web Site 489

Using OpenElement with OLE Objects Syntax http://Host/Database/View/Document/FieldName/FieldOffset/$OLEOBJINFO/ FieldOffset/obj.ods?OpenElement Note The current URL syntax for referencing images and objects in Notes documents specifically the FieldOffset makes it impractical to create these URLs manually. As an alternative, you may paste the actual bitmap or object in place of the reference, create URL references to files stored in the file system, or attach the files to the documents.

URL commands for searching for text


Search-related URLs are available for performing view, multiple-database, and domain searches. Typically you define a URL that displays an input form either a customized search form or the default search form to let users define their own searches, but you may also define a URL that performs text searches without user input. Both input and results forms may be customized.

SearchDomain
Use SearchDomain URLs for text searches across a domain. The search input form is opened with the OpenForm command by name or universal ID. For search results, the results template is specified as part of the URL. If no template is found, then the default template form, $$SearchDomainTemplate, is substituted. If $$SearchDomainTemplate is not found, an error will be returned. If no results are returned, the value of the $$ViewBody field remains the same. Syntax http://Host/Database/[templateForm]?SearchDomain[ArgumentList] Where: templateForm is an optional argument that calls the search results form. ArgumentList is a list of optional arguments. Example http://www.mercury.com/mersrch.nsf/MercuryResults?SearchDomain

490 Application Development with Domino Designer

Redirect
The server will provide a direct or redirect URL command as needed for links displayed on the results form if the capability has been enabled. The domain URL locates information on the server where the links are generated. The redirect command locates the correct server and redirects a link to that server by constructing the appropriate URL. The redirect command can improve performance by resolving individual links when they are selected instead of resolving all of the links returned at once. See Domino 5 Administration Help for information about enabling a redirect URL command on a server.

SearchSite
Use SearchSite URLs for text searches in multiple databases. Because the URL requires the name of a search site database, be sure to create one before using a SearchSite URL. Syntax http://Host/Database/[$SearchForm]?SearchSite[ArgumentList] Where: $SearchForm and ArgumentList are optional arguments. Example http://www.mercury.com/mercsrch.nsf/$SearchForm?SearchSite

SearchView
Use SearchView URLs to limit a search to documents displayed in one database view. This URL is useful for views that display all documents (so you can have a full-database search) or for views in which you can predict what users need to see, such as all documents whose status is Completed. Syntax http://Host/Database/View/[$SearchForm]?SearchView[ArgumentList] Where: $SearchForm and ArgumentList are optional arguments. The special identifier $SearchForm indicates that Domino will present a search view form for search input. If this identifier is provided, the ArgumentList is ignored. If this identifier is absent, a default form will be generated on the fly based on the contents of the search.htm file located on the server. The default form generated by the server does not support paged results.

Appendix E: Programming a Web Site 491

Example http://www.mercury.com/products.nsf/By+Product+Number/$Search Form?SearchView Optional arguments for SearchSite and SearchView $SearchForm The special identifier $SearchForm indicates that Domino will present a search site form for search input. If this identifier is provided, ArgumentList is ignored. The ArgumentList must contain the Query argument; in addition, it may contain any or all of the other arguments in any order. Query = the search string Count=[n] Where n is the number of results to display on each page until the SearchMax has been reached. For example Count=10 will display 10 results per page. SearchEntry = the name of the form to use for the results of a domain search. The default argument is ResultEntry, which supports all of the pre-defined results fields specified in the ArgumentList. This argument is valid for SearchDomain only and should not be used for SearchSite or SearchView. SearchFuzzy=[TRUE,FALSE] Where True = use fuzzy search. The default is FALSE. SearchOrder=[1,2,3] Where 1 = Sort by relevance, 2 = Sort by date ascending, 3 =Sort by date descending. The default is 1. SearchMax=[n] Where n is the maximum number of entries returned. The default value is determined by the server. SearchWV=[TRUE, FALSE] Where TRUE = include word variants in the search. The default value is TRUE. Start=[n] Where n is the number corresponding to the document that appears first in your list of results. For example, Start=10 begins your list of results with the 10th document found in the search. Start=0 means that paged results will not be returned.
492 Application Development with Domino Designer

Examples http://www.mercury.com/mercsrch.nsf/?SearchSite&Query=product+inf o+requests&SearchOrder=2&SearchMax=30&SearchWV=TRUE&Search Entry=myResultsForm http://www.mercury.com/products.nsf/By+Product+Number/?Search View&Query=PC156&SearchOrder=3&SearchMax=1&Search Fuzzy=TRUE&SearchWV=FALSE

URL search syntax and customized results


The following parameters for SearchView and SearchSite URL commands will allow you to display search results page-by-page and to provide buttons or hotspots to navigate between pages. Start and Count parameters Start and Count parameters allow you to display search results page-by-page and may be included as arguments in the SearchView or SearchSite URL commands or as items in the search results form. The Start parameter is the entry that appears first when your results are displayed. The Count parameter is the number of results that will display on each screen. For example, if Start=5 and Count=10, the search results would display beginning with the 5th entry and would display up to 10 entries per screen until the maximum number of entries has been displayed. These parameters work with customized forms only. Syntax http://Host/Database/ViewName/[$SearchForm]?SearchView[ArgumentList] http://Host/Database/ViewUNID/[$SearchForm]?SearchView[ArgumentList] http://Host/Database/ViewNoteID/[$SearchForm]?SearchView[ArgumentList] Where: ArgumentList includes the Query argument and any or all of the other arguments including the Start and Count parameters. For example: ?SearchView&Query=String&Start=n&Count=n&SearchOrder=n&SearchWV= TRUE or FALSE&SearchFuzzy=TRUE or FALSE&SearchMax=n. Examples http://www.mercury.com/products.nsf/ProductView?SearchView& Query=bicycles&Start=21&Count=20&SearchOrder=1&SearchWV= TRUE&SearchFuzzy=FALSE&SearchMax=50 http://www.mercury.com/products.nsf/F6025FD7E72456F9852565400058 39D3?SearchView&Query=bicycles&Start=21&Count=20&SearchOrder=1& SearchWV=TRUE&SearchFuzzy=FALSE&SearchMax=50

Appendix E: Programming a Web Site 493

Using Next and Previous buttons or hotspots with Start and Count parameters
If you are using Start and Count parameters you can include Next and Previous buttons or hotspots to enable users to navigate between pages of results. Both parameters must be used if you are using navigational buttons. 1. Open your customized results form and place buttons or hotspots labeled Next and Previous where you want them to appear on the form. 2. For the button or hotpsot labeled Next, write a formula that will advance the user forward one page. 3. For the button or hotspot labeled Previous, write a formula that will take the user back one page. Example of a formula for a Next button or hotspot @If(Hits >= Count; @URLOpen(/ + @Subset(@DbName; -1) + / + SearchView + ?SearchView&Query= + @ReplaceSubstring(Query; ; +) + &Start= + @Text(Start+Hits) + &Count= + @Text(Count) + &SearchOrder=+@Text(SearchOrder) +&SearchWV=+@If(SearchVw = 0;FALSE;TRUE)+&SearchThesaurus=+@If(SearchThesaurus = 0;FALSE;TRUE) + &SearchMax= + @Text(SearchMax)); ) Example of a formula for a Previous button or hotspot @If(Start > Count; @URLOpen(/ + @Subset(@DbName; -1) + / +SearchView + ?SearchView&Query= + @ReplaceSubstring(Query; ; +) + &Start= + @Text(Start-Count) + &Count= + @Text(Count) + &SearchOrder=+@Text(SearchOrder) +&SearchWV=+@If(SearchVw = 0;FALSE;TRUE)+&SearchThesaurus=+@If(SearchThesaurus = 0;FALSE;TRUE) + &SearchMax= + @Text(SearchMax)); ) Tip To avoid syntax errors, use @ReplaceSubstring(Query; +) to replace all of the spaces in your query with plus signs (+).

URL commands for requiring authentication


Login argument
To force user authentication regardless of the database access control list, append the Login argument to any Domino URL. This ensures that anonymous Web users who werent initially prompted for a name and password when they entered the site are required to supply a name and password to complete tasks that require user identity.

494 Application Development with Domino Designer

Syntax http://Host?OpenServer&login http://Host/DatabaseDirectory/DatabaseFileName?OpenDatabase&login Examples http://www.mercury.com?OpenServer&login http://www.mercury.com/sales/leads.nsf?OpenDatabase&login

URL commands for processing SSL certificates


The following commands automate the request and receipt of Secure Sockets Layer (SSL) certificates stored in a database.

OpenForm with SpecialAction argument


Syntax http://Host/Database/FormName?OpenForm&SpecialAction=special ActionField Where: specialActionField is the name of an editable text field on the form whose value contains a predefined command. To use the field with SSL certificates, use one of the following certificate request commands: SubmitCert ServerRequest ServerPickup For more information about the OpenForm command, see URL commands for opening agents, forms, and navigators earlier in this chapter. Examples http://www.mercury.com/certs.nsf/UserCertificateRequest?Open Form&SpecialAction=SubmitCert http://www.mercury.com/certs.nsf/ServerCertificateRequest?Open Form&SpecialAction=ServerRequest http://www.mercury.com/certs.nsf/Certificate?OpenForm&Special Action=ServerPickup

Appendix E: Programming a Web Site 495

Creating an SSL User Certificate


The SubmitCert command creates a User Certificate document in the specified database, using the form specified in the TranslateForm argument. Syntax http://Host/Database/ResultForm?RequestCert&Command=Submit Cert&TranslateForm=TranslationFormName Where: ResultForm is a form in the specified database that displays information about the processed request. TranslationFormName represents a form in the database that contains fields to hold certificate information. Example http://www.mercury.com/certs.nsf/CertificateProcessed?Request Cert&Command=SubmitCert&TranslateForm=Certificate Optional and required fields The SubmitCert command requires a translation form with a field named Certificate. Domino saves information about the certificate subject and issuer in the document if the form contains fields with these names: CommonName Org OrgUnit Locality State Country IssuerCommonName IssuerOrg IssuerOrgUnit IssuerLocality IssuerState IssuerCountry

Creating an SSL Server Certificate Request


The ServerRequest command creates a Server Certificate Request document in the specified database, using the form specified in the TranslateForm argument.

496 Application Development with Domino Designer

Syntax http://Host/Database/MessageForm?RequestCert&Command=Server Request&TranslateForm=TranslationFormName Where: ResultForm is a form in the specified database that displays information about the processed request in the users browser after a successful submission. TranslationFormName represents a form in the database that contains fields to hold certificate information. Example http://www.mercury.com/certs.nsf/CertificateProcessed?Request Cert&Command=ServerRequest&TranslateForm=Certificate Optional and required fields The ServerRequest command requires a translation form with a field named Certificate. Domino saves information about the server request in the document if the form contains fields with these names: CommonName Org OrgUnit Locality State Country

@functions and @commands


Most @functions are supported in Web applications. If you are familiar with the formula language, use @functions as a quick way to add programmability to a form. Since browsers dont provide menus for Web applications, Domino supports @commands that allow users to work at a Web site, including the ability to open and edit documents, delete documents, open a view, or change to another view. See Formulas for information about using @commands and @functions.

Appendix E: Programming a Web Site 497

Java, JavaScript and Visual Basic Script


The following programming languages may be used in Web applications by entering them into HTML or $$HTMLHead fields, or marking them as passthru HTML. Java JavaScript Visual Basic script For more information on Java programming, see the Domino Designer Programming Guide, Volume 3: Java Classes.

JavaScript
JavaScript allows you to create interactive applications that can run interchangeably on your companys intranet or on the Internet. In JavaScript, most of the information processing is done on the client side. This increases the efficiency of your applications by reducing the amount of traffic between the client and the server. JavaScript may be entered into the JS Header object on the Objects tab in the Programmers pane, as passthru HTML, or into a $$HTMLHead field. See Adding Automation to Applications for information about using JavaScript in Domino.

Perl Scripts
Domino supports programs written in Perl. Perl programs have file names that end with .pl. Place Perl programs in the cgi-bin directory. By default, Domino looks in directories that are included in the servers PATH statement for a Perl interpreter named perl.exe. To override this default, define an environment variable (PERLBIN) that gives the name or absolute path of the Perl interpreter. For example, c:\perl5\bin\perl.exe.

Common Gateway Interface (CGI) programs


CGI is a standard for connecting external applications with HTTP servers. CGI programs allow you to do some background processingon a Web page. To run CGI programs, place them in the default cgi-bin directory or in a directory that has execute access. Because Domino does not maintain access control at the file system level, scripts must include access control measures to prevent unauthorized use.

498 Application Development with Domino Designer

Running a CGI program


To run a CGI program, include the URL to the CGI program file and enclose it in brackets. Note that you can pass arguments for example, values from fields in the form to the CGI program. For example: [http://www.lotus.com/cgi-bin/register.exe? + Email + &&& + LastName + &&&] A CGI program can run immediately after the user submits a document. You might do this when you want to use the Notes API to further process the data. To run a CGI program this way, add a field named $$Return, and use HTML instructions as the field value.

CGI variables
When a Web user saves a document or opens an existing document, the Domino Web server uses CGI variables to collect information about the user, including the users name, the browser, and the users Internet Protocol (IP) address. To capture this information in a Web application: Create a field with the name of a CGI variable. Create an agent whose script contains a CGI variable as a DocumentContext property.

Creating a field with the name of the CGI variable


When a field is named after a CGI variable, Domino copies the field value from the CGI environment and places it in the field. This feature is useful in computed-for-display fields and for determining hide when conditions. 1. Create a field and give it the name of a CGI variable. For example, to obtain the IP address of the user submitting the form, add a field named Remote_Addr to the form. 2. Select the hide-when field properties Previewed for Editing and Opened for editing so users cannot enter information in it.

Appendix E: Programming a Web Site 499

Using the DocumentContext property in Web agent scripts


The DocumentContext property of the NotesSession class is useful in Web-run LotusScript agents. When an agent is executed using the ?OpenAgent command, the DocumentContext property returns a Notes document that contains all CGI variables that are applicable to the session. When an agent associated with a document (through the forms query open agent or query save agent) is executed, the values of that document can be accessed via the DocumentContext property. You can use these values to collect or process information for the current session. Agents used this way must be shared agents and be set up to run manually. To use the DocumentContext property, precede an agent script with these lines:
Dim session As New NotesSession Dim doc As NotesDocument Set doc = session.DocumentContext

Note If the agent runs with the WebQueryOpen or WebQuerySave form events, the document returned by DocumentContext does not automatically contain CGI variables. You must add fields with CGI variable names directly to the form to capture session information. Example: Using the DocumentContext property in Web agent scripts This script uses the Print statement and the CGI variable remote_user to display User = and the Web users name. The script sets the DocumentContext before executing the rest of the script. The variable assumes a text list.
Dim session As New NotesSession Dim doc As NotesDocument Set doc = session.DocumentContext Print "User = " + doc.remote_user(0)

Table of CGI variables


Domino captures the following CGI variables through a field or a LotusScript agent. You can also capture any CGI variable preceded by HTTP or HTTPS. For example, cookies are sent to the server by the browser as HTTP_Cookie.

500 Application Development with Domino Designer

For more information about CGI environment variables, see: http://hoohoo.ncsa.uiuc.edu/cgi/env.html


Field name Auth_Type Returns If the server supports user authentication and the script is protected, this is the protocol-specific authentication method used to validate the user. The length of the content, as given by the client. For queries that have attached information, such as HTTP POST and PUT, this is the content type of the data. The version of the CGI spec with which the server complies. The MIME types that the client accepts, as specified by HTTP headers. The URL of the page the user used to get here. Indicates if SSL mode is enabled for the server. The browser that the client is using to send the request. The extra path information (from the servers root HMTL directory), as given by the client. In other words, scripts can be accessed by their virtual path name, followed by extra information that is sent as PATH_INFO. Returns the same as Path_Info, but decodes the string. For example, if a URL references a view name that contains characters that are not allowed a URL, the name is encoded. This CGI variable decodes the string. Path_Info_Decoded is available to Domino applications only. The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it. The information that follows the ?, or in some cases the !* in the URL that referenced this script. Returns the same as Query_String, but decodes the string. For example, if a URL references a view name that contains characters that are not allowed in a URL, the name is encoded. This CGI variable decodes that string. Path_Info_Decoded is available to Domino applications only. continued

Content_Length Content_Type

Gateway_Interface HTTP_Accept HTTP_Referer HTTPS HTTP_User_Agent Path_Info

Path_Info_Decoded

Path_Translated

Query_String Query_String_Decoded

Appendix E: Programming a Web Site 501

Field name Remote_Addr Remote_Host Remote_Ident

Returns The IP address of the remote host making the request. The name of the host making the request. This variable will be set to the remote user name retrieved from the server. Use this variable only for logging. Authentication method that returns the authenticated user name. Supported only for agents. Contains the data sent with an HTTP POST request. The data is usually URLencoded, consisting of name=value pairs concatenated by ampersands. For example, FirstName=John&LastName=Doe The method used to make the request. For HTTP, this is GET, HEAD, POST, and so on. A virtual path to the script being executed, used for self-referencing URLs. The servers host name, DNS alias, or IP address as it would appear in self-referencing URLs. The name and revision of the information protocol accompanying this request. The port to which the request was sent. The name and version of the information server software running the CGI program. The version of the CGI spec with which the server complies.

Remote_User Request_Content

Request_Method Script_Name Server_Name Server_Protocol Server_Port Server_Software Server_URL_ Gateway_Interface

*If your Domino server is configured to allow search engines to search your Web site, Domino will generate URLs with an ! (exclamation point) instead of a ? (question mark). If this is the case the Query_String CGI variable includes the information that follows the exclamation point. Domino always recognizes both the question mark and the exclamation point, but only generates URLs with the exclamation point if your site is accessible to Web search engines. Generating URLs with an exclamation point makes them more searchable.

502 Application Development with Domino Designer

Index
Symbols
$$fields $$Return, 112 $$ViewBody, 490 listed, 161, 394 @commands for application automation, 294 Programmers pane and, 5 referencing, 146 Web use of, 23, 497 @Db commands @DbColumn, 140, 430 @DbCommand, 430 @DbLookup, 140, 430 described, 425 $fields $Anonymous, 359 $HLFormula field, 144 $PublicAccess, 360 $title, 83 $UpdatedBy, 359 $VersionOpt, 162 listed, 161 @functions @DialogBox, 108 @PickList, 110 @Prompt, 109 for date and time calculations, 133 for external data access, 140 Programmer's pane and, 5 referencing, 146 using, 211 Web, 463, 497

A
About This Database document creating, 377 inheriting from template, 399 launching, 26 OpenAbout command, 480 Access database, 48, 349 defined, 347 documents, 351 folders, 351 forms, 353, 354 outlines, 46 restricting through outline settings, 48 sections, 369 views, 351 Access Control List. See ACL Access levels list of recommended, 389 Access list, 355 Accessibility for users with disabilities, 35 Accessing data. See Data access ACL access levels, 389 agent security and, 275 CGI and, 498 copying from template, 19 database, 349 URL commands and, 494 using to enter names, 137, 139 Web previewing and, 38 Action bar described, 257 Action bar applet, 22, 257 Action buttons and screen readers, 36 creating, 253 Action hotspots creating, 265 defined, 248 deleting, 265 editing, 265 hiding, 265

Numbers
1-2-3 files importing into views, 445

Actions adding, 220 built-in, 247 changing automation for, 254 copying, 254 creating, 253 creating hotspots for, 265 deleting, 254 described, 13, 246 displaying as buttons, 253 editing, 259 examples, 247 inserting, 258 menu, 254 naming, 300 navigator, 230 OLE and, 340 publishing, 326 shared, 31, 258 simple, 246 URL commands and, 476 using to simulate Notes menus, 254 Web, 464 Actions field, 394 Actions menu described, 254 ActiveX defined, 326 Address Book provider Domino Directory and, 455 Address lookups in multiple Domino Directories, 455 Agent Log described, 279 size limit, 284 Agent Manager described, 249 recording less information, 283 setting up debugging, 278 AgentRunner described, 284 Agents, types of built-in, 249 embedded, 277

Index 503

foreground or background, 276 local or server, 276 LotusScript and Java, 274 public access, 360 Agents, uses for adding fields with, 395 editing documents with, 395 hiding design with, 409 mail responses, creating, 422 mailing with, 422 removing field data with, 395 removing stored forms with, 396 renaming fields, 396 resaving documents with, 395 Agents, working with Agent Manager debugging, 282 automated components of, 268 calling, 254, 262, 277 chaining together, 289 compared to servlets and CGI programs, 432 copying, 268 creating, 267 debugger settings, 280 debugging, 277 deleting, 268 described, 13, 248 disabling, 268 enabling, 272 examples, 272 finding creator of, 276 invoking, 433 naming, 300 properties of, 432 renaming, 391 replication conflicts and, 271 run-time statistics, 281 run options, 269 running, 254 running on the Web, 500 scheduling, 267 security, 273, 434 simulating a run, 277 specifying servers for, 267 uses for, 432 viewing, 249 viewing the log, 279 Web and, 464 Aliases action names, 300 agent names, 300 choice list, 140

converting to full names, 141 form names, 87 servlet names, 437 view names, 181 All by Category view, 186 Alternate HTML, 309 Alternate text tag for images and Java applets, 35 Annotating applications, 381 documents, 95 fields, 380 Anonymous forms, 90 Anonymous field, 359 AppletBase extending, 315 Applets action bar, 257 adding to a page or form, 70 BeanMachine and, 304 described, 431 editor, 126 Java, 303 listed, 22 outline, 51 servlets and, 431 view, 216 Applications annotating, 381 automating, 245, 340 completing, 375 deploying, 383 documenting, 377 mail-enabled, 414 master design copies, 383 overview of Domino, 1 previewing, 37 security for, 347 setting launch properties for, 25 testing, 389 Asterisks as passwords, 142 Attaching signatures, 368 Attachment fields Web and, 25 Attachments creating, 71, 102 displaying information about, 197 on pages and forms, 71

opening with URL commands, 487 Attributes HTML, 156 Authentication certificates and, 350 URL commands and, 494 Authors anonymous, 90 displaying names, 197 Authors field creating, 351 described, 356 restricting read-access with, 356 Autolaunching defined, 331 examples, 334 objects, 74, 325 Automating applications, 340 described, 13, 245 formulas for, 294 hiding components, 302 JavaScript and, 295 navigators, 234 replies, 422 security features and, 294 using LotusScript, 291 Averages calculating, 206

B
Background processing on Web pages, 498 Backgrounds for pages and forms, 68 Base class property for Java applets, 310 Billing forms for, 111 reserved fields for, 160 Bitmap graphics. See Graphics Blank databases, 20 BMP files. See Graphics Body field, 160, 394 Borders for frames, 170 Browsers proxy settings for, 39 setting up for previewing, 39 using Print statement to instruct, 291

504 Application Development with Domino Designer

Button bar, 257 Buttons creating, 261 customizing, 258 defined, 248 deleting, 261 editing, 261 examples of, 262

C
CAB files, 306 Calculating cell values, 206 field values, 128, 196 values for computed fields, 146 Calendar controls adding to a page or form, 72 creating, 134 Web use of, 465 Calendar views creating, 177, 465 defined, 173 using with the group scheduler, 102 Cascading action names, 301 agent names, 301 form names, 87 view names, 183 Cascading Style Sheet. See CSS Catalog database, 349 Categories adding to views, 185, 187 columns, 187 field for creating, 161, 187 formulas for, 187 naming, 187 subcategories, 188 Categorized view aliases and, 141 Categorizing by users, 185, 188 documents, 186 Category fields, 187 cc:ing. See Forwarding, Routing cc:Mail mailing to, 419 Certificates, SSL, 494 CGI defined, 498

CGI programs compared to servlets and agents, 432 invoking, 433 properties of, 432 security for, 434 uses for, 432 CGI variables agents and, 500 fields and, 499 table of, 500 user profiles and, 499 Character translation file, 444 Checkbox fields aliases in, 140 creating, 137 in Web applications, 465 Choice list fields aliases in, 140 creating, 137 refreshing, 151 views and, 110 Choices displaying in lists, 110, 137 refreshing, 152 Class name, 305 Classes CSS, 28 Notes, 314 CLS files, 444 CodeBase property for Java applets, 310 COL files creating, 448 defined, 448 for importing a tabular text file, 450 formulas and, 449, 452 guidelines, 449 keywords, 449 Collapsing columns, 197 sections, 369 views, 207 Color palettes changing, 21 for choosing colors, 64 using to blend colors, 31 Colors blending with user's system, 33 for columns, 207

for frame borders, 171 for navigators, 233 for outline entries, 50 for rows, 207 for unread marks, 222 for views, 207 for Web applications, 21 palettes for, 64 Column descriptor file. See COL files Column width, 450 Columns adding to views, 180 calculating values in, 206 categorized, 185 collapsing, 197 copying, 179 date, 223 deleting, 179 entering names from, 139 expanding, 197 formatting, 223 hiding, 207 HTML and, 205 icons in, 200 linking to documents, Web, 205 mapping to fields in views, 448 numbers, 224 programming, 194 referred to in formulas, 211 response, 214 specifying data type in views, 449 styling, 207 switching to a view, 205 testing, 387 time, 223 titles for, 184 views and, 10, 173 width, 207, 451 Combobox fields aliases in, 140 creating, 137 Common Gateway Interface. See CGI Common name displaying, 136 Compatibility with previous releases, 304 See also Release 4; Upgrading Components sizing, 330 using, 326

Index 505

ComposedDate field, 160 Compression. See Zip files Computed fields CGI programs and, 499 defined, 146 examples, 150 order of evaluation, 85 Computed for display fields, 147 Computed text, 58 Computed when composed fields, 147 Conflict documents, 90 See also Replication conflicts Console commands, 280 Controls calendar, 72, 102, 139 date/time, 133 embedded, 102 Cookies, 75 Copy Java applet, 313 CORBA properties for Java applets, 310 CORBA SSL security for Java applets, 311 Count parameter Domino URL commands and, 490 search results and, 494 Create menu documents and, 87 CreateDocument command, 483 CSS class and objects, 28 described, 28 passing information, 162 styles applied to objects, 28 Currency fields for, 128 formatting in columns, 224 formatting in Number fields, 128 Custom controls adding to forms, 328 described, 326 read-mode and, 331 running, 331 sizing, 330 updating, 331 Customizing databases, 17 sorting order for columns, 204 templates, 398 window titles, 95

D
Data access with @DbColumn and @DbLookup, 140 with Domino Connectors, 426 with Lotus Enterprise Integrator, 426 with ODBC, 428, 429 with servlets, 431 Data entry fields for, 146 Data types. See Field types Database icons creating, 376 replacing, 406 Database management shared resources and, 30 stored forms and, 82 Database synopsis, 391 Databases See also Applications access control lists, 349 access to, 349 agent access, 275 blank, 20 connecting to, 425 copying, 18 creating, 16, 402 creating a test copy, 278 default views, 210 defined, 2 documenting, 377 external, 428 hiding, 411 icons, 481 launch properties, 25 launching into framesets, 172 linking, 402 mail features and, 417 naming, 18 ODBC and, 428 previewing, 27 properties, changing, 23 renaming, 391 replacing design of, 406 response forms, 92 restricting creation of new, 275 SSL protected, 350 summary, 391 titles for, 17 unlinking, 409 URL commands and, 477

Datalens ODBC and, 429 Date/Time controls, 133 Date/Time fields described, 129 examples, 135 Date picker adding to a page or form, 72 in Web applications, 465 Date separator, 130 Dates calculating by formula, 133 columns for, 223 displaying, 223 entering, 129, 133 formatting, 130, 132, 223 stored as seconds, 136 Debug_AMgr statement, 282 DEBUG_OUTFILE statement, 283 Debugging agents, 277 Java applets, 320 NotesLog class, 283 Decimal places in Number fields, 129 Decimal symbol, 129 Decrypting documents, 363 DECS described, 425 Default active field, 153 encryption, 365 field values for editable fields, 148 headers and footers, 92 views, 210 DeleteDocument command, 483 Deploying applications, 383 Design action buttons, 4 Design bookmarks icons, 4 Design changes making, 403 preventing in image resources, 32 templates and, 17 Design elements automating, 266 copying, 18 hiding, 411 linking, 402 listed, 2 named, 260 previewing, 37

506 Application Development with Domino Designer

protecting, 408 templates and, 402 updating, 404 Design list, 4 Design pane, 4 Design synopsis creating, 391 described, 14 Designer starting, 3 work area overview, 4 Designs changing, 407 default, 181 hiding, 18, 409 linking, 402 maintaining, 388 preventing changes, 383 refreshing, 404 replacing, 406 replication and, 407 synopsis of, 391 templates and, 397, 409 testing, 385 unlinking, 409 updating, 404 Details. See Expanding Dialog boxes creating, 108 designing, 109 displaying, 337 Dialog forms, 108 Dialog list fields, 137 Discussion template, 16, 441 DocBase property for Java applets, 310 Doclinks. See Links Document Library template, 442 Document Object Model, 5 Document Save dialog box overriding options, 419 Document selection formula, 189 DocumentContext property in Web agent scripts, 500 Documenting applications, 377 fields, 380 Documents About This Database, 377 accessing, 351, 356 agent access, 275 agents and, 395 annotating context of, 95 anonymous, 90

calculating age of, 135 categorizing in views, 186 conflict, 90 copying, 287 copying from templates, 19 creating, 87, 483 decrypting, 363 deleting, 287, 483 displaying in views, 189, 194, 196, 197 editing, 395 footers, 92 form redesign and, 393 forms and, 81 headers, 92 help, 381 hiding, 337 launching, 378 launching as dialog boxes, 337 launching into framesets, 172 linking in workflow applications, 415 mailing, 290, 417 marking read or unread, 287 modifying, 156, 380, 395, 483 moving, 289 opening by key, 485 previewing, 27 profile documents, 106 public, 360 reassigning to forms, 396 removing form from, 396 resaving, 395 response, 92 security for, 351, 355, 356, 361, 368 sending summary, 290 sorting in views, 201 storing forms with, 162 tracking, 111 unread, 222 updating, 393 URL commands and, 484, 485 Using This Database, 377 version tracking, 93 viewing deleted, 178 views and, 186, 189, 194, 195, 197, 201 Web, 87 Domains searching, 490 Domino-generated fields. See Reserved fields

Domino Connectors described, 426 Domino Directory accessing, 455, 457 Address book provider and, 455 using to enter names, 139 Domino Directory Server document servlet manager settings, 435 Domino Global Workbench, 27 Domino Java Virtual Machine (JVM), 435 Domino Servlet Manager, 434 Domino URL commands authentication and, 494 count parameter, 493 implicit and explicit, 486 maximum size, 475 opening documents by key, 485 server commands, 477 ServerRequest, 496 start parameters, 493 syntax, 475 DominoObject in URL commands, 476 Duration controls creating, 135 in Web applications, 465 setting separator for, 155

E
ECL setting up for secure Java applet access, 314 Edit mode for forms and documents, 90 hidden data in, 29 Editable fields defined, 146 EditDocument command, 483 Editing documents, 395 fields, 360 forms, 393 images with the editor applet, 467 navigators, 230 restricting, 356 URL commands and, 484 window titles, 95 Editor applet described, 22 using, 126

Index 507

Editors anonymous, 90 sections and, 369 tracking, 359 E-mail. See Mail Embedded controls date picker, 72 file upload control, 102 forms and, 102 group scheduler, 102, 465 Embedded elements group scheduler, 102 keyboard accessibility and, 36 pages and, 71 reserved fields for, 160 Embedding defined, 327 folders, 219 navigators, 215, 240 objects, 325 outlines, 45, 46 views, 215, 218 Enabling editor applet, 127 encryption, 365 Notes/FX, 343 Encapsulated documents, 419 Encryption default, 365 defined, 361 enabling, 365 examples, 143, 363 fields, 363, 365 Encryption keys creating, 364 defined, 361 examples, 367 fields for, 160, 366 listing, 366 password fields and, 143 secret, 161 Entry helper button, 138 ERP systems connecting to, 425 Error executing agent error message, 284 Events agent, 252 calendar view, 251 click, 252 database, 250 described, 249 examples, 266 field, 252

folder, 251 form, 251 page, 75 programming, 250 view, 250 Examples access, 358 actions, 256 agents, 422 autolaunching, 334 automating navigators, 236 buttons, 262 choice list field generation, 140 columns, programming, 195 computed fields, 150 customizing window titles, 96 Date/Time fields, 135 default value formulas, 149 displaying documents in a view, 190 encryption, 363 encryption keys, 367 events, 266 exchanging data, 344 fields, 344 fields that control mailing options, 420 hiding, 339 hotspots, formula pop-up, 264 hotspots, text pop-up, 263 inheriting information, 158 input translation formula, 150 Java servlet, 439 links, 261 password fields, 142 restricting access, 352 routing review requests, 413 security, 358 servlet, 439 servlets.properties file, 439 templates, 399 Excel files importing and exporting to, 443 Exchanging field data, 342 Execution Control List. See ECL Expanding columns, 197 sections, 369 views, 207, 479 Exponential notation, 129 Exporting from views, 452 Java applets, 314

External database access with Domino Connectors, 425 with Lotus Enterprise Integrator, 425 with ODBC, 428, 429 ExternalData parameter in Java applets, 317 Externalization for Java applets, 317

F
Field-exchange. See Notes/FX, Notes Flow Field data deleting from documents, 122 reassigning, 123 shared fields and, 124 Field formulas creating, 146 described, 148 Field help writing, 380 Field label defined, 124 Field names described, 124 requirements for, 124 Field types defined, 121 list of, 125 listed for choice list fields, 138 Field values calculating, 146, 196 default for editable fields, 148 displaying, 194, 394 Fields, types of Authors, 351, 356 Category, 187 checkbox, 138 choice list fields, 138 combobox, 138 computed, 85, 146 computed for display, 147 computed when composed, 147 Date/Time, 129 dialog list, 138 editable, 146 embedded elements, 160 for data entry, 146 Formula fields, 144 hidden, 90 HTML, 157 listbox, 138 mail-enabling, 160

508 Application Development with Domino Designer

Names, 136 Numbers, 128 Password fields, 142 Radio button, 138 Readers, 351, 355 reserved, 160, 394 Rich text, 126 shared, 122 Text, 126 Fields, working with adding to existing documents, 395 annotating, 380 CGI variables and, 499 copying, 122 creating, 121, 342 default active, 153 default values for, 128, 148 defined, 81 deleting, 122 described, 121 editing, 360 encrypting, 363 examples, 344 exchanging data in, 326 formulas, 148 hiding, 61, 153, 154 HTML attached to, 156 inheriting documents in, 158 inheriting values in, 158 layout regions and, 155 modifying, 288 naming, 124 recalculating computed, 148 renaming, 125, 396 replacing field values, 288 resizing, 156 setting input validation formula, 148 setting translation formula, 148 shared resources as, 31 signing, 368 Web and, 465 File field, 394 File formats importing from and exporting to views, table for, 443 File upload control, 102 Flat style outline, 48 Floating point arithmetic, 129 Folder pane, 11 described, 41 embedding, 219 FolderOptions field, 164

Folders access to, restricting, 351 adding documents to, 161, 164 copying documents to, 287 creating, 227 defined, 227 embedding, 219 hiding, 351 MAPI Folder Interface and, 456 removing documents from without deleting, 287 security, 353 Web, 227 Fonts applying to text, 57 changing in a form, 58 Footers creating, 92 Foreign language applications designing for, 27 Foreign symbols translating, 444 Form buttons creating multiple on Web, 23 Form elements listed, 80 Form processed confirmation, 112 overriding, 162 Formatting columns, 223 dates, 223 HTML, 156, 210 numbers, 224 text, 57 times, 223 views, 210 Forms, types of anonymous, 90 billing, 111 dialog, 108 customized results forms, 493 Domain Search forms, 113 profile forms, 106 response, 92 version tracking, 94 Forms, working with access lists and, 351 Authors fields on, 351 autolaunching and, 332, 336 choices on, 110 compared to pages, 53, 79 copying, 84 creating, 79, 84, 360 default form selection,

overriding, 83 deleting, 84 described, 79 designing, 85, 332 designing prompts, 109 dialog boxes as, 108 displaying as Web page, 483 displaying documents with forms, 82 displaying without editable fields, 483 edit mode, 90 embedded controls on, 102 embedded navigators and, 241 embedding objects in, 327 examples, 344 field-exchange in, 326 footers on, 92 headers on, 92 hiding, 88 improving performance of, 118 launching an OLE object, 333 linking objects in, 327 naming, 86 navigators and, 228 objects and, 325 OLE and, 328 Readers fields on, 351 redesigning, 393 removing, 396 renaming, 391 replication and, 90 restricting access to, 355 storing, 396 storing with documents, 82, 162 templates and, 160 testing, 119, 384 Web applications and, 466 Web users access to, 89 window titles, 95 Formula fields described, 144 programming, 144 Formula language in Web applications, 497 Formula pop-ups creating, 263 defined, 248 deleting, 263 editing, 263 Formulas COL files and, 452 columns and, 194 creating, 263

Index 509

deleting, 263 dialog box, 108 editing, 263 entering in the Script area, 5 field, 146 for automating applications, 294 input translation, 146, 148 input validation, 146 literalizing, 144 lookup, 211 prompting users, 109 providing Web navigation with, 220 view, 189 Forwarding documents, 417 restricting, 355 Frames borders for, 167, 170 described, 165 in Web applications, 468 naming, 168 scroll bar for, 171 sizing, 170 specifying a target frame, 169 Framesets content for, 168 creating, 166 defined, 12, 165 keyboard accessibility and, 36 launching automatically, 165 opening with URL commands, 481 outlines and, 52 From field, 160 Full-text index copying settings, 18

choosing colors for, 64 copying, 232 creating, 66 database management and, 31 design tools for, 231 dynamic, 32 hiding, 32 importing, 232 layout regions and, 101 navigators and, 231 pasting, 232 shared resources, 30 text over, 155 Gray scale using to blend colors, 33 Group calendars in Web applications, 465 Group scheduler using, 102 Guides. See Outlines, Navigators

H
Headers creating, 92 Headlines database described, 144 subscriptions and, 30 Help creating, 377 displaying, 328 writing, 380 Hide-when conditions CGI fields and, 499 field settings, 154 options, setting, 29 Hiding automated components, 302 button hotspots, 261 columns, 207 databases, 411 design elements, 29, 411 designs, 18, 409 documents, 337 examples, 339 fields, 61, 153, 154 folders, 351 formula pop-ups, 264 graphics, 32 Java applets, 311 link hotspots, 260 menu choices, 239 objects, 339 outline entries, 47

G
getCodeBase in Java applets, 323 getDocumentBase in Java applets, 322 GIF files. See Graphics Global Workbench. See Domino Global Workbench Graphical date/time controls, 133 Graphics adding to navigators, 231 adding to outline entries, 46 alternate text for, 35 backgrounds, 68 changing when moused over, 33

paragraphs, 153 section titles, 369 servlet names, 438 subforms, 97 text pop-ups, 263 views, 183, 221, 239, 351 Hierarchy. See Expanding views, Response documents Hierarchical name displaying as common name, 136 Home pages creating, 53 defined, 56 launching, 56 specifying, 382 URLs, 382 Horizontal rules creating, 59 in Web applications, 469 Host forms, 108 Hotspots action hotspot, 265 and imagemaps, 69 button hotspot, 261 creating, 234 defined, 13, 234 examples, 248 formula pop-up hotspot, 263 link hotspot, 260 navigators and, 234 text pop-up hotspot, 262 URLs in, 260 Web applications and, 469 HTML adding, 205 alternate text tag, 35 attributes, 156, 309 columns and, 205 core attributes, 28 displaying information with Print statement, 291 field, 157 formatting, 156, 210 generating for hidden fields, 91 on pages and forms, 73 passing to server, 162 referencing objects with JavaScript, 28 tag attributes, 28 viewing frameset source, 167 views and, 210 HttpSession instance, 436

510 Application Development with Domino Designer

I
Icons creating database, 376 displaying in columns, 200 Image files, 489 Image resources as dynamic graphic, 32 changing, 34 creating, 32 described, 30 inserting, 34 maintaining, 31 sharing among databases, 34 Image set described, 32 Imagemaps described, 69 Images. See Graphics Imperial measurement, 129 Importing column format, 444 documents, 444 files into views, 443, 452 foreign characters and symbols into views, 444 graphics, 232 Java applets, 305 lines per page, 446 navigators, 241 Indenting documents, 196 response documents, 213 Indexes deleting, 225 refreshing, 225 settings, copied, 18 view, 225 Info field, 394 Infoboxes. See Dialog boxes, Properties boxes Inheriting creating fields for, 158 documents in fields, 158 field values, 149 related documents, 93 subjects in a response hierarchy, 159 Input forms, 108 Input translation formulas defined, 148 example, 150 settings for field, 148

Input validation formulas defined, 148 Inserting subforms, 98 International characters displaying on the Web, 127 in Web applications, 467 Items. See Field data

J
JAR files, 306 Java servlets, 431 Java applet properties Base class, 310 CodeBase, 310 CORBA classes, 310 CORBA SSL security, 311 DocBase, 310 Size, 310 Java applets alternate text for, 35 as shared resource, 31 BeanMachine and, 304 compared to servlets, 431 copying, 313 debugging, 320 deleting, 313 Domino, listed, 22 enabling on workstation, 304 exporting, 314 hiding, 311 importing, 305 linking to, on the Web, 306 overview, 303 pages and, 70 parameters, 307 persistence for, 317 refreshing, 314 requirements for, 304 running, 308 security, 314 selecting, 313 serialization, 319 servlets and, 431 setting HTML attributes, 309 shared resources, 312 starting, 313 stopping, 313 storing files for, 304 Troubleshooting, 320 Web and, 22 Web applications and, 498

Java compiler, 434 Java Debug Console, 320 Java programs creating for agents, 299 editing and the Reference tab, 5 importing into agents, 299 restricting use in agents, 274 servlets, 431 storing, 31 using for data access, 426 Java servlets, 434 JavaScript, 75 automating applications with, 295 editing, and the Reference tab, 5 table of supported objects, 296 Web applications and, 498 JavaScript code passing, 162 JavaScript header for pages and forms, 75 JDBC using for data access, 426 JPEG graphics. See Graphics

K
Keyboard accessibility, 35 Keyboard shortcuts and form names, 87 Keys. See Encryption keys Keywords COL files and, 449 See also Choice list fields

L
Labels fields, 124 Language preference setting, 27 Launch properties for pages or forms, 74 Launching databases, 25 databases into framesets, 172 documents, 378 documents or pages into framesets, 172 framesets, 165 home pages, 56 links, 26 objects, 74, 325

Index 511

pages, 26 target frames and, 169 Layout regions changing, 100 defined, 81 described, 99 fields in, 155 graphics in, 101 read access, 29 unsupported features, 138 Legacy databases connecting to, 425 Legend group scheduler, 105 Levels. See Expanding views, Response documents Line wrap in Web views, 175, 185 Linking columns to documents, 205 databases, 402 design elements, 402 designs, 402 documents, 415 mail, 415 objects, 325 templates and, 402 Links creating, 127, 260 defined, 247 deleting, 260 displaying, 205 editing, 260 launching automatically, 26 on pages and forms, 62 sending, 415 target frames and, 169 Links field, 394 Listbox fields aliases in, 140 creating, 138 Lists of choices displaying, 110 Login argument, 494 command, 477, 494 URL command guidelines, 476 Logout command, 477 Lookup formulas, 211 Lookup options for names, 136 Lookups creating, 111 view lookups, 137, 139, 141

Lotus components using, 326 Lotus Enterprise Integrator described, 426 Lotus palettte grays, 33 See also Color palettes LotusScript browser window, 5 debugger, 278 for application automation, 291 OLE and, 327 restricting use in agents, 274 storing programs, 31 using for data access, 426 Web agents and, 500 Web and, 464 LS:DO using for data access, 425

M
Macros. See Agents Mail agents, 422 applications, 414 automatic, 415 changing default font of, 58 fields, 418 fields for automatic, 417 fields for enabling, 160 forwarding, 417 in workflow applications, 414 linking, 415 MAPI classes and methods, 459 sending, 416, 419 Mail-in Database agents and, 422 creating, 421 Mail-in Database Document described, 421 Mail file accessing, 455 Mail integration overview, 455 Mail messages delivery, 456, 457 MAPI, 457, 459 non-Notes, 457 Mail option fields examples, 420 Mail queue outgoing, 456 Mail router, 457

Mail Send dialog box overriding choices, 419 Mail template changing fonts in, 58 MailFormat field, 419 Mailing documents, 416 Main class name, 305 MAPI Address Book provider, 455 classes and methods, 459 defined, 455 Message Store provider, 456 Message Transport provider, 457 overview, 455 platforms, 457 recipient types, 457 requirements, 457 service providers, 455, 456, 457 spooler, 457 MAPI Folder Interface and folders, 456 Maps. See Outlines, Navigators Master design copies creating, 383 Menu bar, 4 Menus actions, 254 displaying, 328 hiding choices, 239 shortcut keys and, 301 simulating for Web users, 254 Message sorting arbitrary, 456 Message store provider described, 456 Message Transport provider address type and, 457 message type and, 457 Messages delivery of, 456 MAPI classes and methods, 459 See also Mail Messaging application program interface (MAPI) Address Book provider, 455 classes and methods, 459 Message Store provider, 456 Message Transport provider, 457 overview, 458 platforms, 457 requirements, 457 service providers, 455, 456, 457 spooler, 457

512 Application Development with Domino Designer

Meta data passing, 162 Metric measurement, 129 Microsoft files importing into views, 445 Microsoft Internet Information Server (MIIS) server commands, 476 Microsoft Office Library template, 442 Mouse-over image creating, 33 Multilingual applications designing for, 27 settings for, 27

N
Named elements defined, 260 Names cascading, 301 displaying, 136 entering from a list, 136 Names dialog box displaying, 137 Names fields described, 136 in Web applications, 465 Naming categories, 187 databases, 18 forms, 86 frames, 168 framesets, 167 views, 181 Native controls, 152 Navigating Web sites, 215, 240 Navigation pane. See Folder pane Navigator templates forms as, 228 Navigators. See also Outlines actions in, 230 automating, 234 color, 233 creating, 229 designing, 229 displaying, 239 editing, 230 embedding, 240 examples, 236 formulas and, 235 graphics and, 231

highlighting, 233 hotspots and, 234 imagemaps and, 69 importing, 241 opening, 239 programming, 230 renaming, 391 scripts and, 235 styling, 233 templates and, 228, 241 testing, 242 text on, 233 Web, 228, 229, 469 web applications and, 229 Notes/FX. See also Notes Flow enabling, 343 in Web applications, 465 setting up, 342 using, 342 NOTES.INI recording debugging information, 283 NOTES.INI settings Default_Index_Lifetime_Days, 225 Notes Browser previewing in, 37 Notes classes setting up applet access to, 314 Notes Client designing for Web and, 21, 90, 127, 157 launch options, 25 search forms and, 113 NotesFlow. See also Notes/FX actions, 326 applications, 325 field-exchange, 326 NotesLog class debugging setting up, 283 Notes Mail. See Mail NotesSession class, 500 NSF files copying, 18 creating, 20 NTF files creating, 388 defined, 16, 397 using, 16 Number fields described, 128 Numbering documents in views, 194

Numbers columns for, 224 formatting in Number fields, 128

O
Object parameter in Java applets, 319 Objects autolaunching, 331 drawing, 232 embedding, 327 enhancing, 233 hiding, 339 hotspot, 234 launching, 325 linking, 327 referencing with JavaScript, 28 resizing, 329 updating, 331 viewing properties and events of, 5 Objects tab, 5 OCX. See Custom controls ODBC data sources, 429 Datalens and, 429 described, 425 using, 428 OLE actions and, 340 applications, 325 autolaunching objects, 336 automating, 340 custom controls, 327 exchanging data, 342 launching objects from a form, 333 launching objects in-place, 335 LotusScript and, 327 publishing actions using, 341 resizing objects, 329 Web and, 325 OLE custom controls. See Custom controls OLE objects autolaunching, 330, 333, 338 launching, 329 opening with URL commands, 489 OpenAbout command, 480 OpenAgent command, 481 Web agents and, 500 OpenDatabase command, 477

Index 513

OpenDocument command, 484 OpenElement command, 489 OpenForm command SearchDomain and, 490 SpecialAction argument and, 495 OpenFrameset command, 481 OpenHelp command, 480 OpenIcon command, 481 OpenPage command, 486 OpenServer command, 477 OpenView command, 477 optional arguments, 479 Ordered lists in Web applications, 467 Outbox folder transferring responses and, 456 Outline applet, 51 described, 22 Outline entries adding graphics to, 47 customizing, 46 described, 42 displaying as a hierarchy, 47 hiding, 47 styles for, 50 Outline views defined, 173 described, 174 Outlines creating, 42 described, 11, 41 designing, 41 displaying in framesets, 52 embedding, 45, 46 styles for, 50 Web users access to, 51 Overriding, 112 default form selection, 83 Form processed confirmation, 162 proxy settings for previewing, 39

P
Page breaks in views, 210 Pages backgrounds for, 68 compared to forms, 53 defined, 53, 74 elements on, 53 embedding controls on, 71 events for, 75 fonts in, changing, 58

graphics on, 66 HTML and, 73 Java applets and, 70 launching, 26 launching into framesets, 172 links and, 62 opening with URL commands, 486 programming, 75 styling text in, 57 Palettes for choosing colors, 64 grays, 33 using to blend colors, 31 Parallel reviews in workflow applications, 413 Parameters setting for Java applets, 307 Password fields described, 142 Passwords URL commands and, 494 PCX graphics. See Graphics Percentage calculating, 206 formatting numbers as, 129 Performance forms and, 85, 118 computed fields and, 147 group scheduler and, 105 headline monitoring and, 30 improving on Web, 24 lookups and, 140 stored forms and, 82 Perl script Web applications and, 498 Persistence Java applets, 317 session, 436 Personal Address Book using to enter names, 139 Personal agents controlling, 274 creating, 267 defined, 249 Web users and, 274 Personal views. See Private views Personal Journal template, 442 Pictures. See Graphics Pop-up calendar controls, 465 Pop-ups formula, 263 text, 262

Precision in Number fields, 129 Predefined fields list of, 160 Preview icons, 4 Previewing applications, 37 databases, 27 documents, 27 framesets, 167 hiding information during, 153 Notes client vs. Notes Browser, 37 setting up, 39 Printing headers and footers, 92 hidden information, 29, 154 restricting, 355 Private views, 178 Profiles creating user, 106 Programmable tables, 60 Programmer's pane, 5 Programming columns, 194 formula language in Web applications, 497 JavaScript in Web applications, 498 navigators, 230 Perl script in Web applications, 498 views, 477 Visual Basic script, 498 Programs creating for events, 266 Projects creating, 284 Prompts creating, 109 displaying, 109 Properties action hotspots, 265 changing, 23 changing database and design element, 23 for Java applets, 310 Properties boxes described, 6 Protecting anonymity, 90 design elements, 408 designs, 408

514 Application Development with Domino Designer

Proxy settings for previewing in browsers, 39 Public access agents, 360 defined, 360 described, 46 documents, 360 forms, 360 framesets and, 167 outlines, 46 views, 360 PublicAccess field, 360

R
Radio button fields, 137 RANGE statement, 450 Read-mode custom controls and, 331 Read access layout regions and, 29 restricting, 354 Read access list folders, 351 forms, 353, 354 views, 351 Readers field, 394 Readers fields creating, 355 described, 351 ReadExternalData parameter in Java applets, 317 ReadForm command, 483 Reading restricting, 353 Redesigning forms, 393 templates, 398 Redirect command, 477 domain search and, 490 Reference list using, 146 Reference tab, 5 Refreshing, 148 choice list field values, 152 defined, 404 designs, 406 field values, 146, 152 Java applets, 314 views, 225 Relational databases accessing with ODBC, 428 connecting to, 425

Release 4.5 attachment fields, 25 Release 4.6 hiding paragraphs from, 153 URL generation, 25 Reloading. See Refreshing Renaming agents, 391 databases, 391 fields, 125, 396 forms, 391 navigators, 391 shared fields, 123 views, 181, 391 Replace Design command defined, 406 Replication disabling, 349 forms and, 90 templates and, 407 Replication conflicts and agents, 269, 271 Replies automating, 422 Report on database design, 391 Reserved fields $Anonymous, 359 $PublicAccess, 360 $UpdatedBy, 359 list of, 160, 394 Reserved form names for navigator or view templates, 228 Resources. See Shared resources Response documents, 92 columns for, 214 displaying, 197 indenting, 213 inheriting subject, 159 limits on, 181 Response forms, 92 Restricting. See also Security access, 347 copying, 355 design changes, 383 editing, 356 examples of, 358 forwarding, 355 printing, 355 reading, 353, 354 Review requests in workflow applications, 413, 442

Revision tracking, 93 Revisions field, 39 Rich text fields, 126 on Web, 126 Rounding in Number fields, 129 Route. See Outlines, Navigators Routing automatically, 414 Rows opening to, 210 spacing, 207 styling, 207

S
SaveDocument command, 485 Schedules coordinating, 102 Scientific notation, 129 Screen-reader software designing for, 35 Script area, 5 Script libraries defined, 31 Scripts creating, 266 deleting, 266 Scroll bars for frames, 171 Search forms, 113 SearchDomain command, 490 SearchEntry, 491 Searches displaying results, 493 navigating through paged results, 116 navigating through results, 494 SearchFuzzy, 491 Searching multiple databases, views, domains, etc., 491 multiple Domino Directories, 455 URL commands and, 490 SearchSite command, 491 count parameter, 493 optional arguments, 491 start parameter, 493 SearchView count parameter, 493 optional arguments, 491 SearchView command examples and syntax, 491 start parameter, 493

Index 515

Secret encryption keys. See Encryption keys Sections access to, 369 collapsing, 369 creating, 61, 369 defined, 80 editors and, 369 hiding titles, 369 Secure Socket Layer. See SSL Security agents, 434 CGI and, 498 CGI programs, 434 database, 349 defined, 347 documents, 351 examples, 358 folders, 353 for agents, 273 for automation, 294 for servlets, agents, and CGI programs, 432 hidden fields and, 153 Java applet access to Notes classes, 314 loading servlet classes, 434 servlets, 434, 438 signatures and, 371 SSL and, 350 SSL certificates, 495 types of, 347 URL commands and, 494, 495 Serial reviews in workflow applications, 413 Server certificate request creating, 496 Server commands OpenServer, 477 Redirect, 477 Server tasks Design, 16 Updall, 225 ServerRequest command examples, 496 optional and required fields, 497 syntax, 496 Servers console commands, 280 restricting creation of databases on, 275 Service providers for MAPI, 455 installing, 457

Servlet API, 434 Servlet classes loading, 436 Servlet manager, 435 Servlets aliases, 434 compared to agents and CGI programs, 432 defined, 431 enabling, 435 enabling Domino support, 434 example, 439 including in applications, 431 initializing, 434 invoking, 433 loading, 438 properties of, 432 running, 434 security for, 434 servlets.properties file, 434 setting properties for, 437 URL extension mapping, 434 uses for, 432 writing, 434 servlets.properties file, 434 example, 439 sessdata.ser, 436 Sessions tracking, 436 Shared actions creating, 258 defined, 246 editing, 259 inserting, 258 Shared agents controlling, 274 creating, 267 defined, 249 on the Web, 500 Shared databases, 414 Shared fields converting to single-use, 124 copying, 122 creating, 122 deleting, 123 inserting, 123 renaming, 123 stored forms and, 83 Shared graphics. See Image resources Shared resources deleting, 313 described, 30 for Java applets, 312 Shared views, 178

Shortcuts menu choices and, 301 Signatures defined, 368 storing, 372 verifying, 372 Signing documents, 368, 371 Simple actions defined, 246 table of, 287 Simple agents. See Agents Simple functions for columns, 197 Site maps. See Outlines Site Registration template, 442 Size property for Java applets, 310 Sorting documents in views, 201 Sorting columns defined, 201 hidden, 204 Sorting order column, customizing, 204 SpecialAction argument, 495 SSL creating user certificates, 496 enforcing for a database, 350 server certificate request, 496 URL commands and, 495 Start parameter search results and, 494 Status tracking, 214 Stop Java applet, 313 Storing files for Java applets, 304 forms with documents, 81, 162 Java code, 31 LotusScript programs, 31 programs, 433 signatures, 372 Structured text files defined, 447 exporting to, 453 importing into views, 447 Style editor applet. See Editor applet Styles CSS, 28 Styling columns, 207 frames, 170 horizontal rules, 59 navigators, 233

516 Application Development with Domino Designer

rows, 207 text, 57 titles, 184 views, 207 Subcategories, 188 Subforms defined, 31, 81 described, 97 examples, 98 Subject field, 160 Submit button generating automatically on Web, 24 SubmitCert command examples and syntax, 496 optional and required fields, 496 Subscription documents storing, 144 Subscription forms creating, 30, 144 Subscriptions described, 144 enabling, 30 Symbols currency, 128 Symphony files importing into views, 445 Synopsis, 391

T
Tab order specifying for fields, 151 Tables in forms, 85 in the editor applet, 467 in Web applications, 470 programmable, 60 Tabular text files COL files and, 450, 453 defined, 445 exporting to, 453 importing into views, 446, 453 Target frames, 169 TeamRoom template, 442 Templates agents and, 398 changing, 397, 403 customizing, 398 defined, 16, 397 design changes and, 17 examples of, 399 fields in, 160 linking, 402

linking to, 402 list of Domino Designer, 441 master, 16 navigator, 241 redesigning, 398 replacing design and, 406 replication and, 403, 407 server, 17 unlinking design elements from, 409 Testing applications, 389 design, 385 forms, 119, 384 navigators, 242 views, 386 Text computed, 58 fields, 126 graphics with, 155 navigators and, 233 styling, 57 Web, 471 Text files exporting, 452 importing to a view, 445, 446, 447 Text pop-ups creating, 262 defined, 247 deleting, 262 editing, 262 Thousands separator setting, 129 TIFF files. See Graphics Time controls creating, 134 in Web applications, 465 Time zone options, 131 Times calculating by formula, 133 columns for, 223 displaying, 223 entering, 130 formatting, 130, 132, 223 Title field, 83, 394 Titles database, 17 frameset, 167 window, 95 Totals calculating, 206 Tracking document status, 214 editors, 359

server usage, 111 sessions, 436 unread documents, 222 versions, 93, 162 TranslateForm argument, 496 Translating applications, 27 applications, and choice list aliases, 140 foreign symbols and characters, 444 Translation formulas defined, 146 setting for fields, 148 Tree style outline, 47 Troubleshooting agents, 277 calendar views, 177 fields, 394 framesets, 172 Java applets, 320 Truncation in imported text, 446

U
Unlinking templates and databases, 409 templates and design elements, 409 Unread marks color, 222 displaying, 222 Updall, 225 UpdatedBy field, 359, 394 Updating custom controls, 331 design elements, 404 designs, 404 documents, 393 Java applet files, 31 objects, 331 views, 225 Upgrading framesets and, 166 Web and, 24 URL commands authentication and, 494 count parameters, 493 explicit, 486 guidelines, 475 home page, 382 implicit, 486 opening documents by key, 485

Index 517

search, 113 searching and, 493 server commands, 477 ServerRequest, 496 start parameters, 493 syntax, 475 URL extensions for Java servlets, mapping, 434 URL links pages and, 62 URLs generating, 477 generating in Release 4.6, 25 in link hotspots, 260 servlet, 433 Use JavaScript when generating pages setting when to use, 23 User profiles creating, 106 Using This Database document creating, 377 inheriting from template, 399 opening with URL commands, 480

V
Values recalculating for computed fields, 146 refreshing, 152 Version control forms for, 94 Version tracking field for, 161 VersionOpt field, 162 Versions conflict documents as, 90 forms for creating, 162 tracking, 93, 162 View applet described, 22, 216 view properties and, 472 View lookups choice list aliases and, 141 choice list fields and, 139 Names fields and, 137 View menu working with framesets and, 170 View template defined, 215 View templates forms as, 228

Views, 449 access to, 351 alias names, 181 All by Category, 186 calendar, 173 categories and, 185 categorized, and aliases, 141 character sorting rules, 201 character translation file (.CLS) and, 444 COL files and, 452 collapsing, 207 columns in, 10 copying, 179 creating, 179, 360 default, 210 defined, 10, 173 deleting, 179 designing, 179 displaying, 210 documents and, 189 embedding, 215, 218 entering names from columns in, 139 exporting, 443, 452, 453 formatting, 210 grouping, 183 hiding, 183, 221, 239, 351 HTML and, 210 icons in, 200 importing, 443, 444 importing tabular text into, 446 indenting in, 213 indexes, 225 limits on, 181 lookups in, 111 mapping imported columns to fields, 448 naming, 181 opening, 210 page breaks and, 210 private, 178 programming, 189 public access, 360 refreshing, 225 renaming, 181, 391 searching, 490, 491 setting line counts, 221 shared, 178 single category, 220 sorting documents in, 201 styling, 207 switching, 205 testing, 386

troubleshooting, 177 types of, 173 unread marks, 222 updating, 225 URL commands and, 477 Web, 175, 471 Vision-impaired users designing for, 35 Visual Basic script Web applications and, 498

W
Web @commands and, 23, 497 @functions, 463, 497 actions, 220, 464 agents, 464, 500 authentication and, 494 CGI variables, 499 creating forms for, 466 documents, 87 example of agents, 272 fields and, 465 file attachments on, 102 folders, 227 formulas, 220 hidden fields and, 90 hiding design elements, 411 improving performance on, 24 Java applets, 498 Java programming, 498 JavaScript, 498 LotusScript and, 464 mailing features, 417 navigating, 215, 240 navigators, 228, 229, 469 Notes/FX and, 326 Perl script, 498 previewing requirements for, 38 private views and, 179 search forms and, 113 security and SSL, 350 Server document and, 382 simulating Notes menus for, 254 tables, 470 text, 471 unsupported features, 24, 133, 137 upgrading and, 24 views, 175, 471 Visual Basic script, 498 Web agent scripts DocumentContext property, 500

518 Application Development with Domino Designer

Web applications color for, 21 designing, 21 displaying text in, 57 home pages for, 56 Notes client and, 15 Web browsers hiding paragraphs from, 153 launch options, 25 proxy settings for, 39 setting up for previewing, 37 using with Notes client, 127 Web elements date picker, 72 embedding on pages, 71 Web pages in frames, 169 Web users access to outlines, 51 attaching files, 102 designing for Notes and, 157 Domino applets for, 22 form access, providing, 89 registering for Domino applications, 442 WebQueryOpen events agents and, 433 described, 272 WebQuerySave events agents and, 433 described, 272 Width columns, 207 Window buttons, 4 Window titles, 95 Windows. See Framesets WindowTitle field, 394 WKSCOL statement, 449 Work area overview, 4 Work pane, 4 Workflow applications, 325, 442 applications, planning, 414 defined, 413 features, 415 overview, 413 Worksheet files COL files and, 448, 449 exporting to, 452 importing into views, 445 WriteExternalData parameter in Java applets, 317 WriteObject parameter in Java applets, 319

Y
Y2K Notes and, 129

Z
ZIP files, 306

Index 519

Potrebbero piacerti anche