Sie sind auf Seite 1von 433

Application Developer's

Guide

Quickly develop secure, collaborative


business applications for the Net

RELEASE
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.
Copyright 1997 Lotus Development Corporation
55 Cambridge Parkway
Cambridge, MA 02142
All rights reserved. First edition printed 1997. Printed in the United States.
List of trademarks
Domino, Lotus Components, Lotus Notes Desktop, Notes, NotesFlow, and Notes/FX are
trademarks and DataLens, Freelance, Freelance Graphics, Lotus, Lotus Notes Mail, Lotus Notes,
LotusScript, 1-2-3, ScreenCam, SmartIcons, SmartSuite, Symphony, and Word Pro are registered
trademarks of Lotus Development Corporation. cc:Mail is a trademark of cc:Mail, Inc., a wholly
owned subsidiary of Lotus Development Corporation. OS/2 is a registered trademark of
International Business Machines Corporation.
International Correctspell English licensed from Houghton Mifflin Company.
Copyright 1991 by Houghton Mifflin Company. All rights reserved.
Reproduction or disassembly of embodied algorithms or database prohibited.
Based upon The American Heritage Dictionary.
Other product and company names mentioned herein may be the trademarks or registered
trademarks of their respective owners.
Contents

About tips for naming forms . . . . . . . . . . . . 30


1 Touring an Application . . . . . . . 1
Creating a database . . . . . . . . . . . . . . . . . . . . . 1 Naming, renaming, and creating
synonym form names . . . . . . . . . . . . . 31
Creating documents .................... 2
Managing how forms appear on the
Opening views and folders . . . . . . . . . . . . . . . 5 Create menu . . . . . . . . . . . . . . . . . . . . 32
Opening navigators . . . . . . . . . . . . . . . . . . . . . 6 About enhancing a form . . . . . . . . . . . . . . . . 33
Viewing the database design . . . . . . . . . . . . . . 7 Adding static text to a form . . . . . . . . . . 33
Opening forms ........................ 8 Adding a graphic to a form . . . . . . . . . . 33
Using the design pane for programming . . . 12 Adding a horizontal line to a form . . . . . 34
Opening the About This Database About adding a form background . . . . . 34
document . . . . . . . . . . . . . . . . . . . . . . . 14
Adding a form background . . . . . . . . . . 35
Opening the Using This Database
Adding a table to a form ............ 36
document . . . . . . . . . . . . . . . . . . . . . . . 15
Adding an attachment to a form . . . . . . 36
Viewing database icons . . . . . . . . . . . . . . . . . 16
About subforms . . . . . . . . . . . . . . . . . . . . . . 37
2 Creating a Database . . . . . . . . 17 Creating a subform ................ 37
About creating databases . . . . . . . . . . . . . . . 17 Displaying a subform on a form ...... 38
Creating a new database from a Examples ........................ 38
template . . . . . . . . . . . . . . . . . . . . . . . . 18
Deleting a subform from a database ... 39
Creating a new database by copying
an existing database . . . . . . . . . . . . . . . 19 About layout regions . . . . . . . . . . . . . . . . . . 39

Creating a new database from scratch . . 21 Creating a layout region . . . . . . . . . . . . . 41

Customizing Notes Designer templates . . . . 22 Adding static text to a layout region ... 41
Adding a graphic to a layout region ... 41
3 Designing Forms . . . . . . . . . . . 25 Aligning and rearranging elements in
About forms . . . . . . . . . . . . . . . . . . . . . . . . . 25 a layout region . . . . . . . . . . . . . . . . . . . 42
About the parts of a form . . . . . . . . . . . . . . . 26 Setting the tab order for fields in a
layout region . . . . . . . . . . . . . . . . . . . . 42
About tips for creating forms . . . . . . . . . 27
Changing the size and style of a
Creating a form ................... 28
layout region . . . . . . . . . . . . . . . . . . . . 42
Deleting a form . . . . . . . . . . . . . . . . . . . . 29
About hiding a layout region . . . . . . . . . 43
About naming, renaming, and creating
Hiding a layout region under certain
synonyms for form names . . . . . . . . . . 29
conditions . . . . . . . . . . . . . . . . . . . . . . 43

Contents iii
About creating form sections . . . . . . . . . . . . 44 Designing a form that lets users make
About types of forms . . . . . . . . . . . . . . . . . . 45 selections from a view . . . . . . . . . . . . . 61

Designating a default form for a About improving document display time . . . 62


database . . . . . . . . . . . . . . . . . . . . . . . . 46 About testing a form before deploying it . . . 63
Designing a response form . . . . . . . . . . . . 47 Previewing the design of a form . . . . . . . 63
About tracking versions of a Testing a form . . . . . . . . . . . . . . . . . . . . . 63
document . . . . . . . . . . . . . . . . . . . . . . . 47
Designing a form for version control . . . . 48 4 Designing Fields . . . . . . . . . . . 65
About storing a form with each About fields . . . . . . . . . . . . . . . . . . . . . . . . . . 65
document . . . . . . . . . . . . . . . . . . . . . . . 49 About assigning data types for fields . . . . . . 65
Storing a form with each document . . . . . 50 About editable and computed fields . . . . . . . 66
Designing a form that protects About field names and labels . . . . . . . . . . . . 68
author/editor anonymity . . . . . . . . . . 50
About predefined fields with built-in
Designing a form that consolidates functionality . . . . . . . . . . . . . . . . . . . . . 68
replication conflicts . . . . . . . . . . . . . . . 51
About standard fields used in Notes
About options for linking in a database . . . . 51 templates . . . . . . . . . . . . . . . . . . . . . . . 69
Linking to a parent document . . . . . . . . 51 Creating a field . . . . . . . . . . . . . . . . . . . . 70
Designing a form that links to a view . . . 52 Creating a field in a layout region . . . . . 71
Designing a form that links to a About shared fields . . . . . . . . . . . . . . . . . . . . 72
database . . . . . . . . . . . . . . . . . . . . . . . . 53
Creating a shared field . . . . . . . . . . . . . . 72
Designing a form that opens
Converting a single-use field to a
documents in edit mode
shared field . . . . . . . . . . . . . . . . . . . . . 73
automatically . . . . . . . . . . . . . . . . . . . . 53
Using a shared field . . . . . . . . . . . . . . . . 73
About customizing window titles . . . . . . . . . 53
About displaying text . . . . . . . . . . . . . . . . . . 73
Customizing the window title . . . . . . . . 55
Creating a field to display text . . . . . . . . 74
Creating a default header and footer
for a form . . . . . . . . . . . . . . . . . . . . . . . 55 About displaying lists of choices . . . . . . . . . 74
About full text searches and forms . . . . . . . . 56 Creating a field to display a list of
choices . . . . . . . . . . . . . . . . . . . . . . . . . 76
Including a form in full text searches . . . 56
About creating synonyms for choices in a
About creating profile forms . . . . . . . . . . . . . 57
list . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Creating a profile form . . . . . . . . . . . . . . 57
About displaying graphics, attachments,
About forms for collecting user input . . . . . . 58 and objects . . . . . . . . . . . . . . . . . . . . . . 80
Designing a form that launches a URL . . 58 About displaying numbers or currency . . . . 80
Designing a form that presents a Creating a field to display numbers or
dialog box . . . . . . . . . . . . . . . . . . . . . . 58 currency . . . . . . . . . . . . . . . . . . . . . . . . 80
Designing a form that prompts users About displaying dates and times . . . . . . . . . 82
for information . . . . . . . . . . . . . . . . . . 60
Creating a field to display dates and
times . . . . . . . . . . . . . . . . . . . . . . . . . . 82

iv Application Developers Guide


About creating fields that inherit values . . . . 85 About shared views . . . . . . . . . . . . . . . . . . 105
Creating a field that inherits values About designing folders . . . . . . . . . . . . . . . 106
from another document . . . . . . . . . . . . 85 About naming a view . . . . . . . . . . . . . . . . . 106
Creating a field that inherits an entire About adding titles to columns . . . . . . . . . . 108
document . . . . . . . . . . . . . . . . . . . . . . . 86
Table of view and column styles . . . . . . . . . 109
About creating fields for version tracking . . . 87
Creating a view . . . . . . . . . . . . . . . . . . . . . . 113
About displaying user names . . . . . . . . . . . . 88
Converting a view to a calendar view . . . . . 114
Creating a field to display user names . . 88
About programming which documents
About looking up names for field values . . . 89 display in a view . . . . . . . . . . . . . . . . 115
About writing formulas for fields . . . . . . . . . 90 Table of document selection
Creating a default value formula for a conditions for views . . . . . . . . . . . . . 117
field . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 About adding programming to columns . . 119
Creating an input translation formula Table of simple functions for columns . . 122
for a field . . . . . . . . . . . . . . . . . . . . . . . 91
About displaying an icon in a column . . . . 123
Creating an input validation formula
for a field . . . . . . . . . . . . . . . . . . . . . . . 92 Table of column icons . . . . . . . . . . . . . . 124
About writing formulas for computed About sorting documents in views . . . . . . . 125
fields . . . . . . . . . . . . . . . . . . . . . . . . . . 93 About overriding alphabetical sorting
Calculating a value for a computed with a hidden column . . . . . . . . . . . . 127
field . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 About using a column to switch to
About improving the run time of another view . . . . . . . . . . . . . . . . . . . 128
formulas and scripts . . . . . . . . . . . . . . 95 About adding categories to views . . . . . . . . 128
About automatically refreshing field About generating category names . . . . . 129
values . . . . . . . . . . . . . . . . . . . . . . . . . 95
About creating an All by Category
Designing a form that refreshes field view . . . . . . . . . . . . . . . . . . . . . . . . . . 132
values automatically . . . . . . . . . . . . . . 96
About indenting response documents . . . . 133
Making a field to display multiple
About formulas for response columns . . . . 134
values . . . . . . . . . . . . . . . . . . . . . . . . . . 96
About formatting date and time columns . . 135
Making a field active by default . . . . . . . 96
About formatting numbers columns . . . . . . 136
About hiding fields . . . . . . . . . . . . . . . . . . . . 97
About generating column totals,
Hiding a field . . . . . . . . . . . . . . . . . . . . . 98
averages, and percents . . . . . . . . . . . . 137
About deleting fields . . . . . . . . . . . . . . . . . . . 99
About defining what users see when they
About fields that prompt users to select open views . . . . . . . . . . . . . . . . . . . . . 138
folders . . . . . . . . . . . . . . . . . . . . . . . . 100
About formulas that look for values in
columns and views . . . . . . . . . . . . . . 139
5 Designing Views . . . . . . . . . . 103
About default views . . . . . . . . . . . . . . . . . . 140
About designing views . . . . . . . . . . . . . . . . 103
About the default design for new views . . . 140
Standard views . . . . . . . . . . . . . . . . . . . . 103
About hiding a view . . . . . . . . . . . . . . . . . . 140
Calendar views . . . . . . . . . . . . . . . . . . . . 104

Contents v
About identifying unread documents . . . . . 141 About agents and the access control
About refreshing view indexes . . . . . . . . . . 143 list . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

About limits for view elements . . . . . . . . . . 145 About events . . . . . . . . . . . . . . . . . . . . . . . . 175


Table of events . . . . . . . . . . . . . . . . . . . . 176
6 Designing Navigators . . . . . . 147 About programming database events . . 178
About navigators . . . . . . . . . . . . . . . . . . . . . 147 About programming view and folder
Creating a navigator . . . . . . . . . . . . . . . . . . 149 events . . . . . . . . . . . . . . . . . . . . . . . . . 179
About adding graphic objects to About programming form events . . . . . 180
navigators . . . . . . . . . . . . . . . . . . . . . 150 About programming field events . . . . . . 181
Adding and enhancing graphics in a About programming action, button,
navigator . . . . . . . . . . . . . . . . . . . . . . 150 and hotspot events . . . . . . . . . . . . . . . 181
Adding text to and highlighting a About programming agent events . . . . . 181
navigator object . . . . . . . . . . . . . . . . . 151
About hiding actions, buttons, and
Adding hotspots to navigators . . . . . . . . 152 hotspots . . . . . . . . . . . . . . . . . . . . . . . 181
About automating navigators . . . . . . . . . . . 153 About programming the automation . . . . . 183
Automating a navigator . . . . . . . . . . . . 153 Table of simple actions for automation
Displaying a navigator when users features . . . . . . . . . . . . . . . . . . . . . . . 184
open a database . . . . . . . . . . . . . . . . . 156 About attaching Java programs to an
About testing navigators . . . . . . . . . . . . . . . 157 agent . . . . . . . . . . . . . . . . . . . . . . . . . 189
Testing a navigator . . . . . . . . . . . . . . . . . 157 Attaching Java programs to an agent . . . 189
About Java Notes classes . . . . . . . . . . . . 190
7 Adding Automation
Creating a form or view action . . . . . . . . . . 190
to Applications . . . . . . . . . . . . . . 159
Creating a button on a form . . . . . . . . . . . . 192
About adding automation to an
application . . . . . . . . . . . . . . . . . . . . . 159 Creating a text or graphic hotspot . . . . . . . . 193
About actions, buttons, and hotspots . . . . . 160 Creating an event script or formula . . . . . . 193
About built-in form and view actions . . . . . 162 Creating an agent . . . . . . . . . . . . . . . . . . . . 195
About the action bar . . . . . . . . . . . . . . . . . . 163 Testing an agent . . . . . . . . . . . . . . . . . . . . . 198
About the Actions menu . . . . . . . . . . . . . . . 164 Checking the Agent Log . . . . . . . . . . . . . . . 199
About naming actions and agents . . . . . 165 Disabling scheduled agents . . . . . . . . . . . . . 199
About designing agents . . . . . . . . . . . . . . . 167 About security features that affect
automation formulas . . . . . . . . . . . . . 200
Table of agent run options . . . . . . . . . . . 168
Table of agent search options . . . . . . . . . 171 8 Restricting Access to and
About choosing which server runs a Securing Parts of an
scheduled agent . . . . . . . . . . . . . . . . . 172 Application . . . . . . . . . . . . . . . . . 201
About running restricted LotusScript About security in an application . . . . . . . . . 201
agents . . . . . . . . . . . . . . . . . . . . . . . . . 172
About controlling access to a database
during design . . . . . . . . . . . . . . . . . . . 202

vi Application Developers Guide


Giving designers access to a database . . 202 About how Notes stores and verifies
Keeping a database private during electronic signatures . . . . . . . . . . . . . 224
development . . . . . . . . . . . . . . . . . . . 203
9 Completing an Application . . 227
About restricting access to documents . . . . 203
About completing an application . . . . . . . . 227
Restricting who can see a view or folder . . . 204
About designing the database icon . . . . . . . 227
Restricting who can update
documents in a folder . . . . . . . . . . . . 205 Creating a database icon . . . . . . . . . . . . . 228
Restricting access to all documents About providing online help for an
created from a form . . . . . . . . . . . . . . 205 application . . . . . . . . . . . . . . . . . . . . . 229
Restricting who can create or read all About creating About and Using
documents from a form . . . . . . . . . . . 206 documents . . . . . . . . . . . . . . . . . . . . . 229
Preventing printing, forwarding, and Creating an About or Using document . . 230
copying of documents . . . . . . . . . . . . 207 About writing help for fields . . . . . . . . . . . 231
About using a Readers field to restrict Writing help for fields . . . . . . . . . . . . . . 232
access to specific documents . . . . . . . 207
Creating and displaying more detailed
About using an Authors field to restrict application help . . . . . . . . . . . . . . . . . 232
who can edit specific documents . . . 208
About controlling what displays when
Restricting who can read or edit the database opens . . . . . . . . . . . . . . . 233
specific documents . . . . . . . . . . . . . . 208
Controlling what displays when the
About tracking who edits a document . . . . 211 database opens . . . . . . . . . . . . . . . . . . 233
Restricting authors from changing Displaying a document preview
fields in existing documents . . . . . . . 211 automatically . . . . . . . . . . . . . . . . . . . 234
About creating forms, views, and agents About checking the application design
for public access . . . . . . . . . . . . . . . . . 212 before rollout . . . . . . . . . . . . . . . . . . . 234
Creating forms, views, and agents for Viewing a summary of the design . . . . . 234
public access . . . . . . . . . . . . . . . . . . . 212
About checking form design . . . . . . . . . . . . 236
About encrypting documents . . . . . . . . . . 213
About checking field design . . . . . . . . . . . . 237
Making fields for encrypting
About checking view design . . . . . . . . . . . . 238
documents . . . . . . . . . . . . . . . . . . . . . 214
About pilot testing an application . . . . . . . . 240
Creating a secret encryption key . . . . . . 216
About restricting design changes . . . . . . . . 241
Enabling encryption for a field . . . . . . . . 217
Making a master design copy of a
Encrypting documents automatically . . . 217
completed application . . . . . . . . . . . . 241
Creating a field that generates a list of
secret encryption keys . . . . . . . . . . . . 218 10 Developing Applications for
About restricting who can edit a section . . . 220 the Web . . . . . . . . . . . . . . . . . . . . 243
Restricting who can access a section . . . . 221 About developing applications for the
About attaching electronic signatures to Domino Web server . . . . . . . . . . . . . . 243
documents and sections . . . . . . . . . . . 222 Glossary of Web terms for application
developers . . . . . . . . . . . . . . . . . . . . . 244

Contents vii
Glossary of Notes Designer terms for About providing menu replacements
Web developers . . . . . . . . . . . . . . . . . 245 for Web users . . . . . . . . . . . . . . . . . . . 266
About planning a Web site . . . . . . . . . . . . . 248 About adding HTML to a Web
About Web settings in the Server application . . . . . . . . . . . . . . . . . . . . . 267
document . . . . . . . . . . . . . . . . . . . . . . 249 Formatting documents with HTML . . . . 267
About Web site home pages . . . . . . . . . . . . 249 Typing HTML directly on a form or
About specifying the Web site home document . . . . . . . . . . . . . . . . . . . . . . 267
page in the Server document . . . . . . . 250 Treating documents as pure HTML . . . . 268
About Web databases . . . . . . . . . . . . . . . . . 251 Adding HTML attributes to a field . . . . . 268
Migrating Notes databases to the Web . . 251 Storing HTML in a field . . . . . . . . . . . . . 268
Specifying an opening page for Web Adding HTML header information to
databases . . . . . . . . . . . . . . . . . . . . . . 252 Web documents . . . . . . . . . . . . . . . . . 269
About creating Web content . . . . . . . . . . . . 253 Using HTML formatting for views . . . . . 271
About previewing your design work on Adding pass-thru HTML to a column . . 271
the Web . . . . . . . . . . . . . . . . . . . . . . . 253 Embedding HTML in agent scripts . . . . 272
Hiding features from Web or Notes users . . 254 About Web graphics and colors . . . . . . . . . 272
About Web documents . . . . . . . . . . . . . . . . 256 Adding text descriptions to graphics
About creating new documents on the and applets . . . . . . . . . . . . . . . . . . . . 274
Web . . . . . . . . . . . . . . . . . . . . . . . . . . 257 About Web fonts and styles . . . . . . . . . . . . 275
Adding computed text to a document About Web agents . . . . . . . . . . . . . . . . . . . . 276
or form . . . . . . . . . . . . . . . . . . . . . . . . 258
About running agents before Web
Creating an attachments field for Web users open or save documents . . . . . . 276
documents . . . . . . . . . . . . . . . . . . . . . 258
About setting up security for Web
About Web views and folders . . . . . . . . . . . 259 applications . . . . . . . . . . . . . . . . . . . . 277
Customizing which column links to Setting up the access control list for a
Web documents . . . . . . . . . . . . . . . . . 261 Web database . . . . . . . . . . . . . . . . . . . 279
About Web navigators . . . . . . . . . . . . . . . . 261 Setting up roles for a Web database . . . . 280
About displaying views and navigators About restricting access to Web views,
with documents . . . . . . . . . . . . . . . . . 261 forms, and fields . . . . . . . . . . . . . . . . 280
Embedding a view, folder pane, or About enforcing encrypted Web
navigator . . . . . . . . . . . . . . . . . . . . . . 262 transactions for a database . . . . . . . . 281
Displaying the view navigation bar About setting up links within a Web site . . 281
for embedded views . . . . . . . . . . . . . 264
About setting up Web searching . . . . . . . . . 282
Using a form as a view or navigator
template . . . . . . . . . . . . . . . . . . . . . . . 264 Setting up view searches . . . . . . . . . . . . 282
Overriding an embedded navigator Setting up multiple-database searches . . 282
with a navigator template . . . . . . . . . 265 About customizing search forms for
About Web buttons and actions . . . . . . . . . 266 Web users . . . . . . . . . . . . . . . . . . . . . 283

viii Application Developers Guide


About customizing the Webs Form
processed confirmation . . . . . . . . . . 285 11 Including Java Applets in
About customizing Web error message
Applications . . . . . . . . . . . . . . . . 311
forms . . . . . . . . . . . . . . . . . . . . . . . . . 286 About including Java applets in
applications . . . . . . . . . . . . . . . . . . . . 311
About customizing the Submit button for
Web forms . . . . . . . . . . . . . . . . . . . . . 287 Preparing to insert Java applets . . . . . . . . . 312
About using @functions in Web About inserting an applet in a form or
applications . . . . . . . . . . . . . . . . . . . . 287 document . . . . . . . . . . . . . . . . . . . . . . 312
About using @commands in Web Importing an applet from your file
applications . . . . . . . . . . . . . . . . . . . . 288 system . . . . . . . . . . . . . . . . . . . . . . . . 313
About Perl scripts . . . . . . . . . . . . . . . . . . . . 290 Linking to an applet on the Web . . . . . . 313
About Common Gateway Interface (CGI) Pasting an applet into a form or
programs . . . . . . . . . . . . . . . . . . . . . . 290 document . . . . . . . . . . . . . . . . . . . . . . 314
About CGI variables . . . . . . . . . . . . . . . . . . 290 About setting applet parameters and
attributes . . . . . . . . . . . . . . . . . . . . . . 315
Creating a field with the name of the
CGI variable . . . . . . . . . . . . . . . . . . . . 291 Setting applet parameters in the
design pane . . . . . . . . . . . . . . . . . . . . 315
Using the DocumentContext property
in Web agent scripts . . . . . . . . . . . . . 291 Editing HTML attributes in the design
pane . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Table of CGI variables . . . . . . . . . . . . . . 292
Editing applet properties in the
About the Domino URL commands . . . . . . 293
Properties box . . . . . . . . . . . . . . . . . . 317
About URL commands for opening
Hiding an applet under certain
servers, databases, and views . . . . . . 295
conditions . . . . . . . . . . . . . . . . . . . . . 318
About URL commands for opening
Refreshing, reorganizing, and
forms, navigators, and agents . . . . . . 297
exporting applet files . . . . . . . . . . . . . 319
About URL commands for opening,
Tips and troubleshooting for Java applets . . 320
editing, and deleting documents . . . . 299
About URL commands for opening 12 Mail-Enabling Applications . 325
documents by key . . . . . . . . . . . . . . . 300
About information flow . . . . . . . . . . . . . . . 325
About URL commands for opening
image files, attachments, and OLE About features that support automatic
objects . . . . . . . . . . . . . . . . . . . . . . . . 302 mailing . . . . . . . . . . . . . . . . . . . . . . . . 326

About URL commands for searching Giving users the form design . . . . . . . . . 327
for text . . . . . . . . . . . . . . . . . . . . . . . . 303 About mailing features and Web
About URL commands for requiring applications . . . . . . . . . . . . . . . . . . . . 328
authentication . . . . . . . . . . . . . . . . . . 305 About fields that control mailing options . . 328
About URL commands for processing Table of fields that control mailing
SSL certificates . . . . . . . . . . . . . . . . . . 306 options . . . . . . . . . . . . . . . . . . . . . . . . 329
About editing the HTTPD.CNF file to About designing a form for optional
add MIME type mappings . . . . . . . . . 308 mailing . . . . . . . . . . . . . . . . . . . . . . . . 332
Setting up a database to receive mailings . . 333

Contents ix
Using an agent to send automatic replies . . 333 Designing a form for documents that
Using an agent to mail notices . . . . . . . . . . 334 open as modal dialog boxes . . . . . . . 354

Using an agent to send announcements . . . 335 Designing a form to hide the Notes
document . . . . . . . . . . . . . . . . . . . . . . 355
13 Designing Applications Hiding an embedded object in a
That Share Information . . . . . . . 337 document . . . . . . . . . . . . . . . . . . . . . . 357

About designing applications that share About using ODBC to access non-Notes
information . . . . . . . . . . . . . . . . . . . . 337 databases . . . . . . . . . . . . . . . . . . . . . . 358

About using NotesFlow tools . . . . . . . . . . . 338 About the files required to use ODBC . . . . . 358

About exchanging data using Notes/FX . . 339 About registering data sources for
ODBC . . . . . . . . . . . . . . . . . . . . . . . . . 359
Preparing a Notes form to exchange
data . . . . . . . . . . . . . . . . . . . . . . . . . . 340 Registering a data source through the
operating system . . . . . . . . . . . . . . . . 359
Enabling and disabling field exchange . . 342
About writing formulas and scripts to
About publishing actions . . . . . . . . . . . . . . 343 access non-Notes databases . . . . . . . . 360
Publishing an action . . . . . . . . . . . . . . . . 344
About linking and embedding objects in 14 Making, Distributing, and
forms . . . . . . . . . . . . . . . . . . . . . . . . . 345 Controlling Design Changes . . . 363
Linking and embedding objects in About making and distributing design
forms . . . . . . . . . . . . . . . . . . . . . . . . . 346 changes . . . . . . . . . . . . . . . . . . . . . . . 363
Adding OLE custom controls to a Renaming a database . . . . . . . . . . . . . . . 364
form . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Renaming forms, views, navigators,
Creating a form that sizes an and agents . . . . . . . . . . . . . . . . . . . . . 364
embedded object . . . . . . . . . . . . . . . . 347 Changing database and design
Creating a form that sizes an OLE properties . . . . . . . . . . . . . . . . . . . . . . 365
custom control . . . . . . . . . . . . . . . . . . 348 About creating a design synopsis . . . . . . . . 365
Creating a form that runs a custom Creating a design synopsis . . . . . . . . . . . 366
control in read-mode . . . . . . . . . . . . . 349
About updating documents after
Letting documents update objects redesigning a form . . . . . . . . . . . . . . . 367
created by forms . . . . . . . . . . . . . . . . 349
About checking field values in a
About forms that launch objects document . . . . . . . . . . . . . . . . . . . . . . 368
automatically . . . . . . . . . . . . . . . . . . . 349
Checking field values in a document . . . 368
Designing a form that launches an
object automatically . . . . . . . . . . . . . . 350 About using agents to update documents
affected by form changes . . . . . . . . . . 369
Designing a form that launches a new
object automatically . . . . . . . . . . . . . . 352 About templates and master templates . . . 371

Launching an object in-place or About creating master templates . . . . . . . . 371


out-of-place . . . . . . . . . . . . . . . . . . . . 353 Converting a template to a master
Specifying the event that causes an template . . . . . . . . . . . . . . . . . . . . . . . 373
object to autolaunch . . . . . . . . . . . . . 354

x Application Developers Guide


Linking a database to a master About importing structured text files . . . . . 393
template . . . . . . . . . . . . . . . . . . . . . . . 374 Importing structured text into a view . . 393
Linking individual design elements to About using a column descriptor file
a master template . . . . . . . . . . . . . . . 374 (.COL) to map a source file to a
About refreshing a design . . . . . . . . . . . . . . 375 Notes view . . . . . . . . . . . . . . . . . . . . . 394
Refreshing a design manually . . . . . . . . 377 About writing a .COL file for a
About replacing a design . . . . . . . . . . . . . . 377 worksheet . . . . . . . . . . . . . . . . . . . . . 395

Replacing the design of a database . . . . . 378 About writing a .COL file for a tabular
text file . . . . . . . . . . . . . . . . . . . . . . . . 396
About design changes and replication . . . . 378
About writing formulas for .COL files . . . . 397
About preventing design changes . . . . . . . . 379
About exporting views . . . . . . . . . . . . . . . . 398
Protecting design elements from being
replaced or refreshed . . . . . . . . . . . . . 379 Exporting a view . . . . . . . . . . . . . . . . . . 399

Unlinking individual design elements C Developing Applications


from a master template . . . . . . . . . . . 380
Using MAPI . . . . . . . . . . . . . . . . . 401
Unlinking a database from a master
About developing applications using
template . . . . . . . . . . . . . . . . . . . . . . . 380
MAPI . . . . . . . . . . . . . . . . . . . . . . . . . 401
About hiding the design of a database . . . . 380
About the Address Book provider . . . . . . . 401
Hiding the design of a database . . . . . . . 381
About the Message Store provider . . . . . 402
About hiding design elements . . . . . . . . . . 382
About the Message Transport provider . . . 403
Hiding design elements . . . . . . . . . . . . . 382
About MAPI recipient types . . . . . . . . . 403
About translating database components . . . 383
About platforms and requirements for
MAPI . . . . . . . . . . . . . . . . . . . . . . . . . 403
A Notes Designer Templates
and Sample Databases . . . . . . . 385 About MAPI classes and methods . . . . . . . 404

Table of Notes Designer master D Features to Avoid Using in


templates . . . . . . . . . . . . . . . . . . . . . . 385
Web Applications . . . . . . . . . . . . 409
Table of Notes Designer sample
Table of Notes form properties that are
databases . . . . . . . . . . . . . . . . . . . . . . 388
not supported on the Web . . . . . . . . . 409
B Importing to and Exporting Table of Notes field properties that are
from Views . . . . . . . . . . . . . . . . . 389 not supported on the Web . . . . . . . . . 410

About file formats you can export and Table of Notes text styles that are not
import . . . . . . . . . . . . . . . . . . . . . . . . 389 supported on the Web . . . . . . . . . . . . 411

About importing options . . . . . . . . . . . . . . 390 Table of Notes view properties that are
not supported on the Web . . . . . . . . . 411
About importing worksheets . . . . . . . . . . . 390
Table of Notes navigator properties that
Importing worksheet data into a view . . 391 are not supported on the Web . . . . . . 412
About importing tabular text . . . . . . . . . . . 391 Table of Notes actions and agent
Importing tabular text into a view . . . . . 392 properties that are not supported
on the Web . . . . . . . . . . . . . . . . . . . . . 413

Contents xi
Table of Notes @functions that are not
supported on the Web . . . . . . . . . . . . 414

Index . . . . . . . . . . . . . . . . . . . . . . 417

xii Application Developers Guide


Chapter 1
Touring an Application

Whether youre developing an application to be used by a few people or


thousands, on an internal network or over the Internet, the design
framework of an application is the same. This chapter provides a tour of the
design elements you use to develop applications in this new environment.

Creating a database
Every Lotus Notes application uses at least one database to organize and
store data and design elements. Database file names end with .NSF and
reside in the Notes data directory or a subdirectory of a Lotus
Domino server a networked machine to which Notes or Internet users
have access. If youre accustomed to Web design, the concept of a database
may be unfamiliar; think of it as a storage area for related Web pages.
The Domino/Notes software includes pre-designed databases called
templates (distinguished by file names that end with .NTF) that help you
create new databases quickly.

Create a sample database


At the Notes workspace, choose File - Database - New and select only those
options shown in the following figure to create a new database derived
from the Discussion - Notes & Web template (discsw46.ntf). Because this is
a sample database, use Local as the server name to create the database on
your local workstation. When you create a real database for others to use,
you choose a server name to create the database on the servers hard drive
instead.

1
When you see an introduction entitled About Discussion, choose File -
Close to proceed directly to the database interior.
The database is now open. Double-clicking the database icon from the
Notes workspace also opens the database. If you close this window, you
close the database. Leave the database open for now.

Creating documents
Documents store the data for an individual database. If youre familiar with
other database products, think of each document as a database record. If
youre accustomed to Web design for the Internet, think of each document
as a Web page.
When you create a new database, it contains no documents. To add a
document, Notes users open the database, choose Create and the name of a
form, fill in information, and close and save the document. Web users click
a button to open a form, fill in information, and then click a Submit button
to close and save the document.
Documents can contain a variety of elements, such as text and graphics. All
documents also have fields data holders that contain one piece of
information, such as a persons name, a comment, a number, a date, or the
results of a calculation.

2 Application Developers Guide


Create sample documents
To create a sample document in your new database, choose Create - Main
Topic. Fill in the fields as shown in the following figure.

Click the Save button on the action bar, then the Close button to save the
document in the database. The view pane on the right shows the name of
your new document. With the highlighting still on the line that contains the
name of your new document, click the Response button.
Fill in the Document title and Message Content fields for this second
document, then click Save and Close. The second document, which is a
response, appears indented under the first document in the view pane.

Chapter 1: Touring an Application 3


Double-click a document to open it. Notice that the brackets have
disappeared around the text you typed. The document is in read mode
now. You cannot change the text until you place the document in edit
mode. The buttons on the action bar are also different than when you first
created the document. Now the action bar shows buttons for tasks you
perform while reading a document.

Click the Edit Document button. Brackets reappear around the editable
fields, allowing you to change information that you entered before.

4 Application Developers Guide


Changing to edit mode changes the buttons in the action bar. Now the
action bar shows buttons for tasks you perform while editing a document.
Click the Close button to return to the viewing windows.

Opening views and folders


A view is the entry point for opening and reading documents. Every
database must have at least one view. When you design a database, youll
probably create several views to organize and present documents in
different ways. If a database is available to both Notes users and Web users,
you might want to create alternate views to enhance the display for each
platform.
Each row in a view represents a single document. To open a document, you
double-click a row. Each column displays information extracted from a
document, such as the author or document title, or the results of a
calculation performed by a column formula. If youre accustomed to Web
design, think of views and folders as index files that have automatic
updating functions, programming features, and graphics.
Like views, folders display documents in a row and column format. Unlike
views, folders dont display documents automatically. Instead, you must
manually move documents into folders.
A Calendar view, which is a variation of a standard view, displays date
blocks rather than rows and columns. You see and open documents within
a date block.

Open the Discussion views and folders


In the folder pane, click each choice listed under Discussion. Notice how
the contents of the view pane changes each time you close the current view
or folder and then open another one. Sometimes the view pane is blank;
sometimes it contains the names of your two sample documents with
document summary information and formatting that are unique to each
view. What you see in the view pane depends on the design of the folders
and views.

Chapter 1: Touring an Application 5


For more information on views, see Chapter 5.

Opening navigators
A navigator provides a graphical way for users to find documents or take
actions in an open database without having to open views or know menu
commands. A navigator that you design to open automatically when a
database opens can also be an entry point for the database or Web site.

Open a navigator
With the database open, choose View - Show - All Documents to replace the
folders list with the navigator named All Documents.

6 Application Developers Guide


In the left pane, click each picture. These hotspots contain instructions for
opening particular views and folders. As you click each picture, notice how
the documents in the view pane change.
Choose View - Show - Folders to return to the Folders and Views list.

Viewing the database design


You created this database from a template, so you automatically received a
number of design elements that determine how this database looks and
functions. To customize a database for a specific use, most developers
modify the design elements they receive or add new ones. If you use
-Blank- as the template for a new database, you must create all the design
elements yourself. You do all database design work from a Notes
workstation, not from a Web browser.

View the design elements in the database


With the database open, return to the folders list by clicking View - Show -
Folders. Click the green triangle next to the word Design to open the Design
toolbox.

Chapter 1: Touring an Application 7


Click a choice listed under Design. The contents of the right pane change
to display the names of individual design elements that are available for
that choice. You perform some high-level design tasks from here such as,
copying and deleting individual elements by highlighting the individual
element and choosing an Edit menu command. If the database contains no
design elements of a specific type, the right pane is blank, as is the case
when you click Shared Fields or Script Libraries.
To enter design mode for an individual element, double-click its name in
the right pane. A design window appears. The design window contains all
the design and programming objects built into or available for the selected
design element.

Opening forms
A form is a framework for entering and viewing information in a database.
The Notes Create menu lists the forms that users can choose for creating
new documents. Most databases have forms for different kinds of
information. For example, a discussion database usually includes a form to
begin a new topic of discussion and another form to respond to topics.

8 Application Developers Guide


If youre familiar with other database products, think of a Notes form as the
screen layout for an application. A Notes form is also similar to a Web input
form that solicits information from users, but unlike a Web input form, a
Notes form can display existing data.
When you design a form, you decide what types of information can reside
in documents created with the form and how the information looks to
users. A form can contain text to identify parts of the document, fields to
store data, graphics to make the form attractive and easy-to-use, HTML
code to format text for Web browsers, Java applets, and links to other
product data. You can also associate forms with other design elements,
such as views and navigators, to create sophisticated Web effects.
Each field on a form stores a specific type of information text; rich text,
which stores styled text, graphics, and multimedia objects; multiple-choice
lists called keywords; numbers; times or dates; and user names.

Open the Main Topic form


With the database open, make sure View - Show - Folders is selected. Click
the green triangle next to the word Design to open the Design toolbox and
then click Forms to see the list of forms in this database.

You have already seen and used two forms when you created your sample
documents: Main Topic and Response. Compare the list of forms you see in
the right view pane against the list of forms available from the Create and

Chapter 1: Touring an Application 9


Create - Other menus. Some forms arent displayed in the Create menus if
they are used for background processes that users dont need to see.
Double-click Main Topic from the forms list to open the Main Topic form in
design mode. The form contains three panes, two of which you see
automatically. Choose View - Action Pane to open the third pane.

The upper left pane is the builder pane where you create and arrange fields,
graphics, and other form elements. For new forms, this pane is empty until
you add the form elements. Click the pane now to make it active, open the
Create menu, and view the kinds of elements you can create on forms.
The action pane in the upper right lists predefined shortcuts built into this
form. Actions display as action bar buttons at the top of documents or as
items on the Actions menu. You can size the right pane by clicking and
dragging its left border.
The design pane at the bottom provides tools for programming form
elements. You can size the pane by clicking and dragging its upper border.

10 Application Developers Guide


Looking at properties for the form
Choose Design - Form Properties to see the properties assigned to this form.

Notice that the leftmost form name is the one you saw on the Create menu
when you created a Main Topic document. Each design element, as well as
the database itself, has a properties box that stores its name, styles, and
options. Click the X in the top right corner to close the properties box.

Looking at fields on the form


Each rectangle on the form represents a field that can hold a piece of
information in a document. When you created your sample Main Topic
document, you entered information in three editable fields: Categories,
Subject, and Body. Three computed fields used formulas to collect your
name and the current date and time: tmpFrom, DateComposed, and
timeComposed.
Scroll through the form until you see the Subject field. Click the field and
choose Design - Field Properties. Click the tabs in the properties box to see
the properties set for the Subject field.
Click other fields to see their properties. Close the properties box when
youre done.

Chapter 1: Touring an Application 11


Using the design pane for programming
The design pane is an editing and tools area where you attach
programming code to design elements. Unless youre writing a script
library or a database script that can be accessed from anywhere in a
database, the code applies only to the design element youre working on.
Most design elements give you the choice of using predefined simple
actions, writing formulas based on the Designer @function language, or
writing scripts based on LotusScript. In addition, you can create agents
that run Java programs written in a separate Java development
environment.
The Notes formula language is a macro language that was derived from
Lotus 1-2-3. It is useful for writing short programs and simulating menu
commands. You can use the hundreds of @functions available in the
language to write your own formulas or choose ready-to-use formulas
called simple actions.
LotusScript is a programming language that is similar to Microsoft
VisualBasic. It is useful for processing multiple documents, performing
looping and branching logic within a program, and exchanging data among
databases. Web databases recognize LotusScript only in agents, so avoid
using it in other design elements when you create a database for Web
browsers.
To add programming code, choose View - Design Pane if it isnt already
selected, select an element from the Define list or click it in the builder pane
or action panes above. Then click the type of program you want to add,
select an event from the Event list, and add the code to the editing area.

Look at scripts and formulas in the Main Topic form


The Main Topic form has scripts and formulas associated with the form, its
fields, and its actions.

12 Application Developers Guide


Click the arrow beside the Define list to scroll through the list of
programmable elements on this form. Click the arrow beside the Event list
box to see the triggers that cause the forms programmable elements to run
a program. Try a variety of Define-Event combinations to view the
programming associated with this form.
Tip To scroll through event scripts for a design element, click the design
pane, and use CTRL+PGUP and CTRL+PGDN to scroll through event code.
Youll see declarations first, then the scripts attached to events.
Choose File - Close to close the form. Click No if you are prompted to save
any changes.

Chapter 1: Touring an Application 13


Opening the About This Database document
Users see the About This Database document when they open a database
for the first time or when they choose Help - About This Database. The
About This Database document can serve as a home page for a database or
a Web site if it contains links, hotspots, and other graphical navigation aids
and you set the database properties to open the document automatically.
If you create a database from a template, the About This Database
document has general information that you should customize for your
database. If you create a database using -Blank- as the template, the About
This Database document is not available until you add text and other
objects and save the document. The document can contain styled text,
collapsed sections, graphics, links, hotspots, HTML, and Java applets.

Open the About This Database document in design mode


In the left navigation pane, with the Design toolbox open, click Other and
double-click About Database Document to open the About This
Database document in design mode. To change or add information, use the
Edit, Create, and Text menus, just as you would in a regular document.

Choose File - Close to close the document. Click No if you are prompted to
save any changes.

14 Application Developers Guide


Opening the Using This Database document
The Using This Database document allows you to add user help that is
specific to the database. To see the Using document, users choose Help -
Using This Database.
If you create a database from a template, the Using This Database
document has general information that you should customize for your
database. If you create a database using -Blank- as the template, the
document is not available until you add text and other objects and save the
document.

Open the Using document in design mode


In the left navigation pane, with the Design toolbox open, click Other and
double-click Using Database Document to open the Using This Database
document in design mode. To change or add information, use the Edit,
Create, and Text menus, just as you would in a regular document.

Choose File - Close to close the document. Click No if you are prompted to
save any changes.

Chapter 1: Touring an Application 15


Viewing database icons
Databases are represented on each Notes workspace by icons. Notes users
double-click an icon to open a database. Web users dont see these icons.

Each database you create comes with an icon. To open the icon in design
mode, click Other from the Design toolbox and double-click Icon.

16 Application Developers Guide


Chapter 2
Creating a Database

Creating a database can be as simple as starting from an existing template,


which already contains the forms and views that you need for your
application, or as complex as starting from scratch, with a blank database
whose forms and views you design.

About creating databases


A database is a structure that holds the data for an application. The
structure is composed of forms, fields, views, and other presentation
features, such as a navigator and a database icon.
There are three ways to create a new database:
Base a database on a template
Copy an existing database
Create a database from scratch

Using a template
The easiest way to create a database is to use a template, which is a file that
contains the structure for the database that is, forms and views but
does not contain documents. Notes Designer comes with a collection of
templates that you can use to create applications quickly. For example, to
design a discussion database, use the Discussion template
(DISCUSS4.NTF), which contains forms that track discussion threads in a
hierarchy, as well as views that display the entries by date, author, or
category.
A template file has a .NTF as its file extension. You can set the database you
create to continue to inherit design changes from the template. Then if
someone redesigns the master template, your database automatically
inherits the new design.
As you consider how to design an application, know who your users are.
Users with Lotus Mail licenses can only see applications created from
templates stamped for their use. You cannot customize those templates in
any way, or the stamping becomes invalid.

17
For a complete list of Notes Designer templates and information on which
templates are available for users with a Lotus Mail license, see Appendix A.

Copying a database
If you have read access to a database that contains the design elements that
you need for your application, copy the existing design and use it as the
basis for a new application. If you copy the design of an existing database,
keep in mind that:
The settings for the full text search 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 index.
Before you copy the design of a database, check its Database Properties.
If Design is hidden is shown on the Design tab in the Database
Properties box, you will never be able to modify the design of the new
database.
In addition to copying the entire design of a database, you can copy
individual design elements.
For information on creating a full text index, see the Database Managers
Guide.

Starting from scratch


The most ambitious way to create a database is to start from scratch. When
you do this, you begin with a blank file that has the extension .NSF. This file
contains no forms, fields, views, or other elements. You must create all of
the forms, fields, views, and other elements that you need for the
application.

Creating a new database from a template


1. Choose File - Database - New.
2. Do one of the following:
Leave Local selected as the server 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 box, enter a title for the new database.
4. (Optional) Press TAB and enter a file name to change the default name
in the File name box.

18 Application Developers Guide


5. Select a template or, if you dont see the template you want, do one of
the following:
Click Show advanced templates and select a template from the list.
Click Template Server to use templates that reside on a server.
6. (Optional) Deselect Inherit future design changes.
7. (Optional) Click Encryption, select Locally encrypt this database
using:, select an encryption type, and click OK.
8. (Optional) Click Size limit and select a size (in gigabytes), and click
OK. The default database size is one gigabyte.
9. Click OK.

Details
Title
The Title can have a maximum of 32 characters. It appears on the database
icon.
Database file name
Specify a unique, descriptive name of fewer than 8 characters, followed by
the extension .NSF. As part of the file name, specify a drive and directory to
store the new database in a specific directory. Otherwise, the database is
stored in the Data directory.
Customizing a database
After creating a database from a template, you will probably customize the
database. Keep in mind that many of the templates that ship with Notes
Designer are master templates. This means that changes made to the
master template are passed on to the databases created from the template.
One side effect of this is that changes you make to a database can be
overwritten by a new version of a template.
If you plan to customize a database and want to avoid the possibility of
overwriting design changes, either deselect the Inherit future design
changes option as described in the steps above, or deselect Inherit design
from template on the Design page of the Database Properties box for the
database.
For information on inheriting design changes, see Chapter 14. For
information on encrypting a database, see Chapter 8.

Creating a new database by copying an existing database


To copy an entire database
1. Select the icon for the database you want to copy.
2. Choose File - Database - New Copy.

Chapter 2: Creating a Database 19


3. Do one of the following:
Leave Local selected as the server to store the database on your
workstation hard disk.
Select or enter a server name to store the database on a server. This
allows multiple people to work on the database design.
4. (Optional) In the Title box, enter a title for the new database. The title
appears on the database icon.
5. Press TAB and enter a new name to change the default file name in the
File Name box.
6. (Optional) Click Encryption, select Locally encrypt this database
using:, select an encryption type, and click OK.
7. (Optional) Click Size limit and select a size (in gigabytes), and click
OK.
8. Select Database design only.
9. Deselect Access Control List.
10. Click OK.
11. (Optional) Highlight the new database icon, choose File - Database -
Properties, and deselect Inherit design from template on the Design
tab to prevent the new database from inheriting design changes from
the master template whose design the source database was based on.

To copy an individual design element


1. Open the database containing the design element you want to copy.
2. Select the element in design mode and choose Edit - Copy.
3. Open the database where you want to paste the element.
4. Click in the design pane for that type of element and choose Edit -
Paste.
If the design element inherits changes from a master template, such as
the standard mail template, Notes prompts you to maintain or break
the link.

Details
Title
The Title can have a maximum of 32 characters. It appears on the database
icon.
Database file name
Specify a unique, descriptive name of fewer than 8 characters, followed by
the extension .NSF. As part of the file name, specify a drive and directory to
store the new database in a specific directory. Otherwise, the database is
stored in the Data directory.

20 Application Developers Guide


Creating a new database from scratch
To design a database from scratch first create an empty database. Then
design the forms, fields, views, and other design elements for the
application.
1. Choose File - Database - New.
2. Do one of the following:
Leave Local selected as the server to store the database on your
workstation hard disk.
Select a server name to store the database on a server. This allows
multiple people to work on the database design.
3. In the Title box, enter a title for the new database. The title appears on
the database icon.
4. (Optional) Press TAB to change the default database file name.
5. (Optional) Click Encryption, select Locally encrypt this database
using:, choose an encryption type, and click OK.
6. (Optional) Click Size limit and select a size (in gigabytes), and click
OK.
7. Select -Blank- as the template.
8. Click OK.

Details
Title
The Title can have a maximum of 32 characters. It appears on the database
icon.
Database file name
Specify a unique, descriptive name of fewer than 8 characters, followed by
the extension .NSF. As part of the file name, specify a drive and directory to
store the new database in a specific directory. Otherwise, the database is
stored in the Data directory.

Chapter 2: Creating a Database 21


Customizing Notes Designer templates
Notes Designer ships with a collection of templates that you can use as is
or customize for your organization. There are two things to consider before
customizing a Designer template:
Certain license types, such as the Notes Mail license, can only access
applications created from Designer templates stamped for use by those
license types. Customizing these templates invalidates the stamping.
Many templates that ship with Notes Designer are master templates.
Changes made to a master template are passed along to databases
created from the template. While this is a powerful way to distribute
design changes, consider that if you customize a template and then
install a new version of Notes Designer, your customization will be
overwritten by the newer version of the template.

Before you customize a Designer template


1. Copy the template and deselect Inherit future design changes.
2. Give it a different file name in the Copy Database dialog box to prevent
future releases of Notes Designer templates with the original file name
from writing over your customized template.
3. Leave the design template name the same in the Database Properties
box, so that existing databases can be synchronized to it.
4. Protect your customized views, forms, subforms, navigators, shared
fields, or agents by selecting each component in the design pane,
choosing Design - Design Properties, and selecting Do not allow
design refresh/replace to modify.
For more information on managing design changes, see Chapter 14. For
more information on Notes Designer templates and their use with certain
license types, see Appendix A.

Examples
Customizing a master template
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.

22 Application Developers Guide


Add the field directly to the master discussion template. Then every
database associated with the master discussion template inherits the new
Confidential field.
DISCUS46.NTF
|- SALES.NSF Sales discussion inherits from DISCUS46
|-TRAVEL.NSF Travel discussion inherits from DISCUS46
Creating a customized version of a master 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. You 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 Do not allow design refresh/replace to modify in the Design
Document Properties box so the new form wont be deleted when the
server resynchronizes the design of mail databases.
The Eastern regions template inherits its design from the Notes mail
template and also serves as a template.
MAIL46.NTF
|-SLEE.NSF Sam Lees mail inherits from MAIL46
|-EASTMAIL.NTF (StdEastMail) Eastern mail template inherits
from MAIL46
|- SBRAUN.NSF Sandy Brauns mail inherits from
StdEastMail

Chapter 2: Creating a Database 23


Chapter 3
Designing Forms

This chapter introduces the kinds of elements you can place on a form,
shows you how to create a form and define its characteristics, and describes
how to design an attractive, readable form.

About forms
A form is a framework for entering and viewing information in a database.
A Notes database contains documents created from one or more forms. A
form can contain:
Fields that store data
Text that labels fields or gives instructions
Subforms that store a collection of form elements you want to use on
more than one form
Layout regions that combine graphics and fields in a way that affords
greater design flexibility
Graphics that make forms easier to understand
Tables that summarize or organize information
Objects (OLE, Subscriptions, Notes/FX fields), file attachments, and
links that extend the reach of Notes documents
Actions and buttons that perform functions automatically
Background color and graphics that enhance the look of a document
If the form you need is similar to one that exists in the same database or
another database, its easiest to copy the form and then modify it. You can
also copy individual forms from the Notes Designer templates. If no
existing form suits your purpose, create a new form.

25
About the parts of a form
Use the following elements to structure the data in a document.

Fields
A field holds a particular type of data. For example, a field might contain
text, a number, or a graphic. You can place fields anywhere on a form. A
field can be unique to that form or shared among forms within a database.
You can encrypt data in a field, attach an electronic signature, or use hidden
fields that calculate data. You can also add LotusScript programs that run
when users move to or from certain fields. Text attributes, such as bold type
or color, that you apply to fields affect the appearance of the data in the
finished document.
Fields can also be Notes/FX fields that exchange information with other
products.

Subforms
A subform is a collection of fields, sections, actions, and other form
elements that are 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 updates. Common uses of subforms include
adding a company logo to business documents or adding mailing label
information to mail and memo forms.

Layout regions
A layout region is a design area on a form that affords greater flexibility for
combining and arranging text and graphics. 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.

Text
You can place static (unchanging) text anywhere on a form and apply text
attributes, such as color, size, and font styles to the text. Text is often used
to label fields so users understand the purpose of each field.

Graphics
You can place a decorative graphic anywhere on a form, and it will appear
on every document created with the form. For example, on a form for
correspondence, place your company logo at the top to create a letterhead.

26 Application Developers Guide


Tables
Tables are useful for summarizing information or aligning fields in rows
and columns. A table placed on a form appears in every document created
with the form.

OLE objects
A form that has an OLE object allows users to view and update data
created in another product from a Notes document. For example, an
Employee Information 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.

Attachments
You can attach files to a form so users can detach files locally or launch
them from every document created with the form.

Links
Within a form, you can add links to databases, views, or specific
documents. You can design the form so when a user opens the document
created with the form, the links automatically launch.

Actions and hotspots


You can automate simple or complex tasks and then attach those tasks to
actions or hotspots on a form. Then users can accomplish tasks with a single
click. You can display form actions on the action bar and the Actions menu.
You can display hotspots directly on the form. Hotspots, in the form of
pop-up text, actions, links, and formulas, are a useful way to automate
static text and decorative graphics.

About tips for creating forms


Placing elements on the form
Use the ruler to set tabs and elements. With the form in design mode,
choose View - Ruler to see the current paragraph settings.
Group related information together. Use sections for approvals or other
special access needs. Use subforms for groups of elements you use
frequently.
Locate particular fields, especially header data, such as name,
department, current date, and due date, in a consistent place and a
consistent order.
Place elements in logical reading order.

Chapter 3: Designing Forms 27


Place hidden fields together at the bottom or top of a form. Assign a
different text color to hidden fields.
Field formulas are computed 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 only at the top of a form. It tends to get lost when
used farther down on the form.
Use a table to align fields on a form.

Streamlining 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.
Use form formulas in a view to shorten a lengthy form for users who
dont need all the information.
Provide actions and hotspots to let users take action quickly and to
control the logic flow.
Use regular collapsible sections to neaten a form and make it easier for
users to see the information they need. Set the properties to expand the
section in one context and collapse it in another.

Creating a form
To create a blank form
1. Select the database and choose Create - Design - Form.
2. If you receive a message about invalidating authorization, click OK if
you do not have Lotus Notes Mail IDs at your site; otherwise, click
Cancel.
3. If you see a list of subforms, click Cancel.
4. Create fields, static text, and other elements on the form.
5. Choose Design - Form Properties to assign a name and other form
properties.
6. Close and save the form.

28 Application Developers Guide


To copy an existing form
1. Copy the form you want to reuse to the clipboard.
2. Paste the copy into the Design - Forms area of the target database.
Shared field definitions are not sent with the copied form. You must
copy shared fields to the new database to avoid the message Cannot
locate field definition.

Deleting 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 in the
default form instead.
1. Open the database.
2. In the navigation pane, choose Design - Form.
3. Choose the form you want to delete.
4. Choose Edit - Clear.
5. If you receive a message about invalidating authorization, click OK if
you do not have Lotus Notes Mail IDs at your site; otherwise, click
Cancel.
6. Click Yes to confirm.
7. Close the database.
Tip To prevent users from seeing 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
Chapter 7.

About naming, renaming, and creating synonyms for form names


The name of every form appears on the Create menu. If a database has too
many forms to display neatly on the Create menu, design a cascading menu
structure to group related forms under one menu item. The Mail (R4)
template uses cascading workflow forms. When users choose Create -
Workflow, they see these form choices:
Workflow\Bookmark
Workflow\Phone Message
Workflow\Task

Chapter 3: Designing Forms 29


Renaming and creating synonyms
To rename a form, create a synonym for it. Synonyms allow you to create a
short name for use in formulas, to maintain existing references to a form
when you need to change the name users see, and to allow for easy
translation of a form name into other languages.
The the form name and its synonyms are separated by | (vertical bars).
If a form has only one name, it appears on the Create menu and in the
documents Form name field in the Document Properties box. If there are
two or more names, the forms first (leftmost) name appears on the Create
menu. The forms last (rightmost) name appears in the FORM field.
Middle names are used only to display documents that were created with
those form names. For example, a database originally released in English
uses an English form name. When you translate the database into Spanish,
you add the Spanish form name in the leftmost position so Spanish users
see the translated name on the Create menu. The English name now moves
to the middle position; documents created with the English form name are
still displayed in the Spanish database.

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.

About tips for naming forms

Begin each form name with a different letter


Windows, OS/2, and UNIX 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

30 Application Developers Guide


Consider how the forms are ordered on the Create menu
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.

Use consistent form-naming conventions


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; it also makes 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.

Naming, renaming, and creating synonym form names


A form can have additional names (synonyms). Using synonyms allows
you to change the form name that appears on the Create menu without
having to rewrite every formula that references a form name, reassign
existing documents to the new form, and rewrite formulas or reassign
documents if the form name is translated.

To name a form
1. Create a new form.
2. Choose Design - Form Properties and enter a name for the form.

To rename a form or add a synonym


1. Open the form in design mode and choose Design - Form Properties.
2. If this form has never been used to create documents, change the name
for the form.
3. If documents have already been created with this form, add the new
name and a | (vertical bar) to the left of any other names. For example:
Interview | Main Topic
4. Close and save the form.
5. If you receive a message about invalidating authorization, click OK if
you do not have Lotus Notes Mail IDs at your site; otherwise, click
Cancel and do not save the form.

Chapter 3: Designing Forms 31


Managing how forms appear on the Create menu
To create a cascading menu
If you dont want to overwhelm users with long lists of forms or if you
want to group related forms, name forms so they cascade from a submenu.
You can create only one level of cascading forms.
1. Open the form in Design mode.
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 a synonym for a cascading form, insert the synonym after the
form name, as in: Service Request \ Hardware | HW, where HW is the
synonym.

To move a form to the Create - Other menu


If you dont expect a form to be used frequently, move it to a dialog box to
shorten the list of forms in the main Create menu.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Select Include in Menu and select Create - Other dialog.

To remove a form from the Create menu


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, form names in parentheses are
also removed from the Create menu.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Deselect Include in Menu.
4. Close and save the form.
To hide a form from only some users, use a create access list.

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. Open the form in Design mode.
2. Choose Design - Form Properties.

32 Application Developers Guide


3. Click the hide tab (the roller shade icon).
4. Choose hide options.
For information on hiding individual design elements, see Chapter 8.

About enhancing a form


In addition to fields, you can add the following to a form:
Text to guide a user through a form.
Background color to improve the look of a form or to communicate a
message about the form. For example, you might always use yellow for
an invoice form.
Background graphics to add interest to a form.
Horizontal lines to separate parts of the form.
Tables to help organize and present data to users.
Attachments to distribute a link to other documents, databases, or files.

Adding static text to a form


You can use static text to label a field or add descriptive information.
1. Open the form in Design mode.
2. Move the cursor to the location on the form where you want to place
the text.
3. Type the text.
4. (Optional) Highlight the text and choose Text - Text Properties to
change its font, style, size, or color or to hide it under certain
conditions.

Adding a graphic to a form


A form that contains a graphic is visually appealing, but takes more time to
display and print. Depending on the type of graphic, you copy and paste it,
or you import it.

To copy and paste a BMP file


1. Copy the graphic to the clipboard.
Tip To copy a database icon, open the icon in Design mode and click
Copy.
2. Open the form in Design mode.
3. Move the cursor to the location in the form where you want to place the
graphic.

Chapter 3: Designing Forms 33


4. Choose Edit - Paste to paste the graphic.
5. Close and save the form.

To import a BMP (bitmap), JPEG, GIF, PCX Image, or TIFF 5.0 bitmap
1. Open the form in Design mode.
2. Move the cursor to the location in the form where you want to place the
graphic.
3. Choose File - Import.
4. Choose the file to import and click OK.
5. Close and save the form.

To change the display of the graphic


1. Select the graphic.
2. Choose Picture - Properties.
3. (Optional) Change the height or width settings for the picture.
4. (Optional) Add text that displays when the picture is loading in a Web
application.
For information on using a graphic as a form background, see Adding a
form background later in this chapter.

Adding a horizontal line to a form


You can add a horizontal line to separate different parts of a form or to add
visual interest.
1. Open the form in Design mode.
2. Place the cursor where you want the rule to start.
3. Choose Create - Horizontal Rule.
4. To edit display settings, double-click the rule to display the Properties
box.

About adding a form background


You can paste or import a BMP (bitmap), JPEG, GIF, PCX Image, TIFF 5.0
bitmap graphic file as a background for a form. If the graphic is the same
size as the form, it appears once; smaller graphics tile to fill the
background of the form. All form elements appear in front of the form
background.
In addition, you can add a background color to enhance a form. For
example, you use a standard color for a particular type of form for
example use white for request forms.

34 Application Developers Guide


You can also allow users to override the background settings at the
document level, to speed up display of a document, to change the
background color, or to import a document-specific background graphic.
This is particularly useful for Web applications, where documents are pages
on a Web site.

Adding a form background


To choose a background form color
1. Open the form in Design mode.
2. Choose Design - Form 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 form
background.
2. Open the form in Design mode.
3. Choose View - Design Properties and click the Background tab.
4. Click Paste Graphic to display the graphic as the form background.

To import a bitmap, JPEG, GIF, PCX Image, or TIFF 5.0 bitmap as a


background
1. Open the form in Design mode.
2. Choose Design - Form Properties and click the Background tab.
3. Click the Import Graphic button and select the file to import.
4. Click OK.

To delete a form background


1. Choose Form - Design Properties.
2. Click the Background tab then click Remove Graphic.

To allow users to override the form background


1. Open the form in Design mode.
2. Choose Design - Form Properties and click the Background tab.
3. Select Allow users to override background properties.
4. Click OK.
For more information, see Adding a picture in Notes Help.
For information on using a graphic as a visual element in a form, see
Adding a graphic to a form in this chapter.

Chapter 3: Designing Forms 35


Adding a table to a form
Use a table to organize information or align fields in rows and columns.
Tables can contain text, buttons, objects, and graphics.
1. Open the form in Design mode.
2. Move the cursor to the location in the form where you want to place the
table.
3. Choose Create - Table.
4. Specify the starting number of rows and columns for the table and click
OK.

Details
Highlight the table or individual rows or columns and choose Table -
Table Properties to change border styles and spacing for the highlighted
area.
Highlight the table or individual rows or columns and choose Text -
Text Properties to change the style of text or to hide text for the
highlighted area.
For more information, see Ways to format tables in Notes Help.

Adding an attachment to a form


Add an attachment to a form to make the file available in every document
created with the form.
1. Open the form in Design mode.
2. Move the cursor to the location in the form where you want to create
the attachment.
3. Choose File - Attach.
4. Select the file and click Create (on Macintosh, click Open).
5. (Optional) To launch the attachment automatically when users open the
document, choose Design - Form Properties, click the Launch tab, and
select AutoLaunch: First Attachment.
For more information, see Attaching a file to a document in Notes Help.

36 Application Developers Guide


About 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.
To control the display of a computed subform, use 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.
Subforms can contain the same elements as a regular form.
For more information, see About forms earlier in this chapter.

Creating a subform
If you cant find a subform that is similar to the one you need, create a new
subform and build its design yourself.
1. Select the database that will have the new subform and choose Create -
Design - Subform.
2. If you receive a message about invalidating authorization, click OK if
you do not have Lotus Notes Mail IDs at your site; otherwise, click
Cancel.
3. Choose Design - Subform Properties.
4. Enter a name for the new subform.
5. Choose options for displaying the subform.
6. Create the subform using the same elements you use to create a form.
7. Close and save the subform.

Display options for subforms


The following options do not apply to computes subforms.
Unless the subform is only to be used on forms through a subform
formula, select Include in Insert Subform dialog so designers see it
when inserting a subform.
Select Include in New Form dialog if you want the subform to appear
immediately when designers choose Create - Design - Form.
Select Hide Subform from R3 Users to hide the contents of a subform
if it contains features, such as layout regions, that arent available to
Release 3 users.

Chapter 3: Designing Forms 37


Details
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.
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 Design mode and copy individual components.

Displaying a subform on a form


To insert a subform
1. Open the form in Design mode.
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 in Design mode.
2. Click where you want to paste the subform.
3. Select Insert Subform based on formula.
4. Click OK.
5. Enter a formula that determines which subform to display.
6. Close, name, and save the form.

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.
2. Choose Edit - Clear.
3. Adjust the formatting if necessary.

Examples
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);

38 Application Developers Guide


Deleting a subform from a database
You can remove a subform from a database permanently.
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - Subforms.
3. Click the subform you want to remove.
4. Choose Edit - Clear.
5. If you receive a message about invalidating authorization, click OK if
you do not have Lotus Notes Mail IDs at your site; otherwise click
Cancel.
6. Click Yes to confirm.
7. Close the database.

Details
When a user opens a document that references a deleted subform, the
message Cannot locate Subform: <subform name> appears. After the user
clicks OK, the document opens with a representation of the deleted
subform. When a designer opens a form that references a deleted subform,
the message Cannot locate Subform: <subform name> appears. After the
designer clicks OK, the form opens. 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 in Design mode.
To avoid these messages, add another subform to the database and give it
the same name as the deleted one.

About layout regions


A layout region is a design area on a form that affords greater flexibility for
combining and arranging text and graphics. Do not use a layout region in a
Web-enabled application.
A layout region can contain:
Static text
Graphics (either in the background or as graphic buttons)
All fields except rich text fields in layout regions have display options
that are not available to fields in forms or subforms.
Buttons

Chapter 3: Designing Forms 39


You cannot add the following elements to a layout region:
Attachments
Hotspots
Links
Objects
Pop-ups
Rich text fields
Sections
Tables
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.

Display options in layout regions


Layout regions allow you to present field data in a more graphical way. For
example, in calendar applications, you can use a layout region to present a
calendar pop-up or a time slider that allows users to block off dates and
ranges of times for calendar entries. The following display options are
available only for keywords fields in layout regions:

Listbox
Each keyword choice is displayed with an expanded list box. Users click an
entry to select it, or, if Allow multi-values is selected for the field, users
can click more than one entry. The Allow values not in this list option is
not available.
List boxes have frame, size, and placement options. To resize the list box
without dragging it, change the Width and Height measurements. To move
the list box in the layout region without dragging it, change the Left and
Top measurements.

Combobox (available only for keywords fields in layout regions)


Each keyword 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. The
Allow multi-values and Allow values not in this list options are not
applicable to combo boxes.
Combo boxes have frame, 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.

40 Application Developers Guide


Creating a layout region
To create a layout region
1. Open the form in Design mode.
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.

Adding static text to a layout region


1. Open the form in Design mode.
2. Click the layout region.
3. Choose Create - Layout Region - Text.
4. Choose Design - Object Properties.
5. In the Properties box, replace (untitled) with the text for the area and
click the green check mark.
6. Edit the layout options to change the size or position of the text area.
Tip For less precise but quicker layout changes, drag the text area to
the size or position you want.

Adding a graphic to a layout region


1. Copy a graphic to the clipboard.
2. Open the layout region in Design mode.
3. Choose Create - Layout Region - Graphic.
4. Choose Graphic Background or Graphic Button as the display option.
5. Edit the layout options to change the size or position of the graphic.
6. Click the Hide tab to adjust the hide properties.
7. Choose Design - Send to Back to position the graphic behind other
elements.

Chapter 3: Designing Forms 41


Aligning and rearranging elements in a layout region
1. Open the form in Design mode.
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.

Setting the tab order for fields in a layout region


Tab order specifies the sequence in which fields become active as a user
presses the TAB key.
1. Open the form in Design mode.
2. Click the first field in the layout region and choose Design - Bring to
Front.
3. Click the second field and choose Design - Bring to Front.
4. Continue with each subsequent field in the sequence, choosing Design -
Bring to Front for each.

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 in Design mode.
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.
5. (Optional) Deselect Show border to make the layout region borders
invisible.

42 Application Developers Guide


6. (Optional) Select 3D style to show the layout region in gray and to
show fields and buttons as they look in dialog boxes.

About hiding a layout region


You can hide a layout region, including its text, graphics, and fields in any
of these situations.
When users edit, hide information that is useful only when users create or
edit documents. When users read, print, and copy, hide information that is
useful when users read documents.
Previewed for reading
The hidden information isnt visible when users read documents in the
document preview pane.
Previewed for editing
The hidden information isnt visible when users work on documents in
edit mode in the document preview pane.
Opened for reading
The hidden information isnt visible when users open documents in
read mode. A layout region that cant be read cant be printed either.
Opened for editing
The hidden information isnt visible when users work on documents in
edit mode.
Printed
The hidden information isnt visible on printed documents.
Copied to the clipboard
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.
Hide paragraph if formula is true
A formula determines the circumstances in which information is
hidden.

Hiding a layout region under certain conditions


1. Open the form in Design mode.
2. Click the layout region and choose Design - Layout Properties.
3. Click the Hide tab.
4. For basic options, select all situations in the Hide paragraph when
document is: section in which the layout region and its components
dont need to be seen by users.

Chapter 3: Designing Forms 43


5. 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.

About creating form sections


Use sections to group and organize fields on a form and display them
according to criteria you specify. You can collapse or hide sections. For
example, on an order form for bicycles, a salesperson might first select a
category of bicycle, such as childrens bikes or mountain bikes. Based on
that selection, a section displays providing additional fields pertaining to
childrens or mountain bikes.

To create a standard section


1. Open the form in Design mode.
2. Highlight the text, fields, and other components to include in the
section.
3. Choose Create - Section - Standard.

To collapse a section
1. Open the form in Design mode.
2. Click the section marker and choose Section - Section Properties.
3. Click the Expand/Collapse tab.
4. Select options for showing the section expanded or collapsed
depending on whether a document is being previewed, printed, or
opened.
5. Select Hide title when expanded if users dont need to see the section
title when the fields are displayed.

To delete a section
1. Click the section title and choose Edit - Clear.
2. Close and save the form.
Details
You can restrict access to a section by creating an access control list.
For information on creating an access-control list for a section, see
Chapter 8.

44 Application Developers Guide


About types of forms
There are several types of forms that have specific meanings in Notes.

Default forms
A default form is the form that you designate to display a document when
the documents associated form is not available.

Main topic forms


A main topic form is the top level in a hierarchy of forms. It can have zero
or more response forms associated with it.

Response forms
The Response form creates response documents associated with a main
document. A response document appears under whichever main document
is highlighted when the user composes a response. Designers often create
response documents that inherit data from main document for example,
the topic title.
The Response-to-response form creates response documents associated
with either a main document or a response document.

How forms are stored


A form is stored in a database and used to display all associated documents
or stored with a document and used to display only that document. It is
best to store the form in the database since storing it with each document
consumes more memory. However, there may be times such as, when
you are mailing a document to a database that does not have the necessary
form to display the document that you need to store the form with the
document.

How Notes determines what form to use


Using a form formula, you can control what form Notes uses to display a
document. For example, you can write a form formula to display a form
containing all fields when a user edits a document and another 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
use the Main Topic form, unless you duplicate the form formula in other
database views.

Chapter 3: Designing Forms 45


In the absence of a form formula, Notes uses these rules to determine which
form to use:
1. If a form is stored with the document, use that form to display the
document.
2. If the view has a form formula, use the formula to display the
document.
3. If no form is stored in the document and there is no form formula, use
the original form that was used to create the document. The internal
Form field in the File - Document Properties box displays the name of
the form. If the original form is not available, use the databases default
form.
4. If the form associated with a document is not available in a database,
Notes uses the databases default form to display the document. Each
database can have only one default form which is marked with an
asterisk (*) in the Forms list.
To override the default form selection to display information in a different
way, write a form formula for a particular view.
For information on writing form formulas, see the Programmers Guide.

Designating a default form for a database


To specify a default form for a database
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Click the Defaults tab.
4. Select Default database form.

To override the default form from the view level


1. Open the view in Design mode.
2. Choose Design - View Properties.
3. Click the Advanced tab (the hat icon).
4. Click Formula Window.
5. Write a formula that determines which form to use and click OK.
6. Close and save the view.
For more information on writing a form formula, see the Programmers
Guide.

46 Application Developers Guide


Designing a response form
A form creates main (parent) documents unless you designate it as a form
that creates response documents.
1. Open a form in Design mode.
2. Choose Design - Form Properties.
3. On the Basics tab, do one of the following:
Select Form Type: Response to use the form for responses to main
documents.
Select Form Type: Response to Response to use the form for
responses to main documents and other responses.
For information on indenting response documents under the preceding
document, see Chapter 5.

About tracking versions of a document


Version tracking allows you to maintain a history of changes to a document.
Version tracking is active only for documents that users create by using the
designated version tracking form. Users can circumvent version control by
editing a document through a different form. 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.
Responses to version-controlled documents display as responses to the
original document.

Displaying updates in the view


You have several choices about how new versions appear in a view:

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.

Chapter 3: Designing Forms 47


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 version become siblings


Use this when all versions have equal importance. The original document is
listed first in the view; all successive versions follow as additional main
documents. Choose this method when you want to leave the original
document as a main document 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.

Designing a form for version control


1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. On the Basics tab, select any Versioning method except None.
4. Select a Create versions option.

48 Application Developers Guide


Details
Versioning methods:
Automatic creates a new version of a new document when the user
saves a document.
Manual creates a new 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.
Computed-when-composed fields are not recalculated when you store
updates as responses or as sibling documents. The responses are copies of
the original document and are not considered newly created.

About storing a form with each document


Storing the form with each document allows the document to display
correctly even in databases where the form is missing or where the form
has been renamed or deleted. Be aware, though, that this option
significantly increases the size of a database and causes additional work if
you change the form design later because there is no easy way to globally
update the form.
When you mail or paste a document that has a stored form, the form is
transferred with it. Because a stored form always overrides a views form
formula, Notes always uses the stored form to display the document.
This feature uses system memory and may require as much as 20 times
more disk space, but using the feature may be necessary if youre sending
documents to another database that doesnt have the correct form available.
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 a
synonym name 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 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.
Fields created in documents with stored forms
When a form is stored in a document, the form name is stored in an internal
field called $Title. Additional information is stored in the $Info,
$WindowTitle, and $Body fields. To use a different form to display the

Chapter 3: Designing Forms 49


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.
LotusScript and mailed documents
As an alternative to storing the form in a document, you can design a form
that you can mail along with a document using a LotusScript program that
uses the Send method. This ensures that the database will have the correct
form to display a document but wont need to store the form with each
document.
For more information on mailing forms with documents, see Chapter 4 of
the Lotus Notes Programmers Guide.

Storing a form with each document


1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Click the Defaults tab.
4. Select Store form in document.
5. Choose Database from the Properties for list.
6. Select Allow use of stored forms in this database.

Designing a form that protects 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.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Select Anonymous Form.

Details
For complete anonymity, be sure that the author name does not appear
elsewhere on the document for example, in a visible computed field.

50 Application Developers Guide


Designing a form that consolidates 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, Notes 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.
1. Choose Design - Form Properties.
2. On the Basics tab, select Merge replication conflicts.
3. Save and close the form.
For more information on replication conflicts, see Notes Help.

About options for linking in a database


You can connect related documents using links from a form to a document,
view, or database. For example, you can create a response form that
includes a link to the response documents parent so that a user
understands the context of the response document. Or, use a link to open a
view when a user opens a document in read mode.

Linking to a parent document


To make it easy for users to find a related document, a form can contain a
link to the related document. For example, a new response document can
include a link to its main document.
1. Open the form in design mode.
2. Create a new rich text field to display the document 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 the rich text field you created in step 4.
7. Select Link.
8. (Optional) Select On Open: Show context pane and Parent.
9. Close and save the form.

Chapter 3: Designing Forms 51


Details
This option takes up less disk space than including the full or collapsed
contents of a parent document because Notes stores only a pointer to the
document rather than a copy of the document.
To create the link, a user highlights the document before choosing Create -
<form name>. 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.

Designing a form that links to a specific document


You can add a link to a particular document for every document created
with this form, and, optionally, open the linked document automatically.
1. Select the database and open the view that displays the document to
which you want to link.
2. Highlight the document and choose Edit - Copy As Link - Document
Link.
3. Open the form where you want to paste the link in Design mode.
4. Place the cursor where you want to paste the link.
5. Choose Edit - Paste.
6. (Optional) Choose Design - Form Properties.
7. (Optional) Click the Launch tab and select AutoLaunch: First
Document Link to jump to the link immediately when existing
documents are opened in read mode.
8. (Optional) Click the Defaults tab and select On Open: Show context
pane and Doclink.
9. Close and save the form.

Designing a form that links to a view


1. Select the database and open the view to which you want to link.
2. In the navigation pane, click the view and choose Edit - Copy As Link -
View Link.
3. Open the form in Design mode.
4. Place the cursor where you want to paste the link.
5. Choose Edit - Paste.
6. (Optional) Choose Design - Form Properties.

52 Application Developers Guide


7. (Optional) Click the Launch tab and select AutoLaunch: First
Document Link to jump to the view link immediately when existing
documents are opened in read mode.
8. Close and save the form.

Designing a form that links to a database


1. Select the database to which you want to link.
2. Choose Edit - Copy As Link - Database Link.
3. Open the form in Design mode.
4. Place the cursor where you want to paste the link.
5. Choose Edit - Paste.
6. (Optional) Choose Design - Form Properties.
7. (Optional) Click the Launch tab and select AutoLaunch: First
document link to jump to the database link immediately when existing
documents are opened in read mode.
8. Close and save the form.

Designing a form that opens documents in edit mode automatically


For users convenience, you can specify that documents created with a form
automatically open in edit mode.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Click the Defaults tab.
4. Select On Open: Automatically enable Edit Mode.
5. Close and save the form.

About customizing window titles


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.

Chapter 3: Designing Forms 53


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);

Examples
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
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.

54 Application Developers Guide


Customizing the window title
1. Open the form in Design mode.
2. Click the design pane and select Event: Window Title for the form.
3. Enter text enclosed in quotation marks or a formula that evaluates to
text.
4. Click the green check mark to save the formula.
5. Close and save the form.
6. 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
Programmers Guide.

Creating a default header and footer for a form


You can define a default header and footer for all documents created with a
form.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Click the Printing tab (the printer icon).
4. Click Header and type the header and/or click Footer and type the
footer.
5. Click the icons to add the date, time, page number, and so on.
6. (Optional) Assign a font, size, and style for header or footer text.
7. Close and save the form.

Details
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.

Chapter 3: Designing Forms 55


About full text searches and forms
When you design an application, keep in mind that at some point you or a
database manager might decide to full text index the database to allow
users to search for specified words or phrases. How you design a form
affects the full text search capabilities.
If you want the form to be used in full text searches, keyword fields that
contain text lists (rather than formulas) can include only the characters
(quotes), @ (ampersand), & (at sign), . (period), \ (backslash), and : (colon)
and letters, numbers, and currency symbols.
If the form uses characters other than these, copy the form and give it a new
name. Remove all restricted characters and objects from the copied form,
and make it available for text searching by selecting Include in Search
Builder. Do not display the copied form in the Create menu.
If you want the forms static text to be included in the Search Builder, you
must also select the Store form in document option on the Defaults tab.
For more information about creating full text search indexes, see the
Database Managers Guide.

Including a form in full text searches


When you make a form available for full text searching, users can select a
form and enter queries into specific field. This option also allows users to
search for text in attachments and embedded objects.
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - Forms.
3. Double-click the form.
4. Choose Design - Form Properties.
5. On the Basics tab, select Include in Search Builder.
6. Close and save the form.
For more information about creating full text search indexes, see the
Database Managers Guide.

56 Application Developers Guide


About creating profile forms
You can create a form that generates profile documents for an application.
Use profile documents to store user-specific values that you need to retrieve
quickly. Profile documents are cached in a users local desktop file while
the database that stores them is open to allow for quick access to the values
they store. You can use profile document as an alternative to setting values
in an .INI file. Profile documents are not created from the Create menu, do
not appear in any views, and are not included in the document count for a
database.
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
db.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 not already
exist.
An example of a profile form is the Calendar Profile form in the Mail4.5
template, which stores default values such as alarm settings for a users
calendar. The profile document is created using the agent Calendar
Tools/Calendar Profile.
For more information about accessing or editing a profile document, see the
Programmers 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.
5. Create a button, action, or agent that uses either the NotesDatabase
GetProfileDocument method or the @Command EditProfile to create or
access the document.

Details
Use the @functions GetProfileField and SetProfileField to access and edit
field values in a profile document.
Use the LotusScript method NotesDatabase EditProfile to edit an existing
profile document.
For information on creating or editing profile documents using an
@Command formula or a LotusScript program, see the Programmers Guide.

Chapter 3: Designing Forms 57


About forms for collecting user input
You can create forms that rely on user input to generate a document. For
example, you can create a form that launches a URL that a user types in.
You can also 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 launches a URL


You can design a form that contains a field in which users enter a URL to be
launched automatically when a user opens a document created with the
form. A form can contain only one autolaunch URL field.
1. Create or open the form on which you want to place the field for
launching a URL.
2. Click the location on the form where you want to create a field for
entering the URL.
3. Choose Create - Field. The field must be a text field.
4. In the Field Properties box, type URL in the Name box.
5. In the Properties for box, select Form.
6. Click the Launch tab.
7. In the Autolaunch box, select URL.
8. Close and save the form.

Designing a form that presents a dialog box


To make it easy for users to fill out documents, display a custom dialog
box. This design requires two forms: the dialog form has a layout region
with fields, text, and graphics that look like a dialog box; the host form
contains a button that uses @DialogBox to display the dialog form.
1. Open the dialog form in Design mode.
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.

58 Application Developers Guide


10. On the Display tab, add a label and width for the button.
11. In the design pane, click Formula, and write a formula using
@DialogBox and the name of the dialog form.
12. (Optional) To share users dialog box selections with the host
document, add fields (except rich text fields) with the same names as
those you created in step 6. (They do not need the same data types or
editable/computed settings as the layout region fields.)
13. Close and save the form.
For information on using @Dialogbox, see the Programmers Guide.

Details
Design guidelines
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 8 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. You cannot remove these buttons or add buttons next to the OK
and Cancel buttons.
Use the multi-column display option with radio button and check box
keyword fields to arrange the keywords horizontally; use None for the
frame option so they blend with the dialog box background.
For button text, use initial capital letters for multiple words. Use
ellipses for buttons that lead to another dialog box or task for
example, Show Details....
Field values entered through the dialog box
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, if a host
form called Memo has a button that uses @DialogBox to bring up the
dialog form called Memo Options and both forms have a field called

Chapter 3: Designing Forms 59


Comments, Comments are identical in both the Memo document and the
Memo Options document.
All values that users enter in the dialog box are stored with the host
document and can be seen in the Document Properties box.

Examples
To make it easy for users to add customer information to a database, you
design a Customer Information form with a button that uses @DialogBox to
call the Dialog Box form.
When users choose Create - Customer Information, they click the button to
add a new customer.
The Customer Information form contains the same field names as the
Dialog Box form fields. When users fill out the necessary information in the
dialog box and click OK, the entries are saved in the Customer Information
document automatically.

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 a simplified version
of @DialogBox because it can contain only text and doesnt interact with
any other forms.
These steps assume you have already created a field, button, hotspot, or
action that will store the @Prompt formula.
1. Open the form in design mode.
2. Choose View - Action Pane and double-click the action, or double-click
the field, button, or hotspot.
3. In the design pane, click Formula.
4. Write a formula using @Prompt.
5. Close and save the form.
For more information on the @Prompt command, see the Programmers
Guide.

Examples
[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. );

60 Application Developers Guide


[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 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 in Design mode.
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 design pane, click Formula.
4. Write a formula using @PickList (and the [Custom] parameter, unless
you want to use [Name] to display a Public or Private Address Book).
5. Close and save the form.
Details
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 Programmers Guide.

Chapter 3: Designing Forms 61


Examples
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 );

About 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 keyword
field, or write a LotusScript field event to recalcaulate 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.

62 Application Developers Guide


For example, suppose a form contains a hidden computed field called
State, which determines where documents are in the workflow and
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 Programmers Guide.

About 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 design pane 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 actual application allows you to create
documents, examine the documents through different views, and test all
actions.

Previewing the design of a form


Preview a form as you design it to see how it will look to a user.
1. Open the form in Design mode.
2. Choose Design - Preview in Notes or Design - Preview in Web Browser.
3. Click Yes to save the form before testing it.
4. Close the test document.
5. Click the form and make any necessary design changes.
6. Close and save the form.
For information on previewing using a Web browser, see Chapter 10.

Testing a form
Always test a new form before giving it to users. For forms that contain
multiple actions or formulas, test and fix each formula or task first. When
everything is working correctly, test the complete form.
1. Select the database and choose File - Database - New Copy to make a
test copy of the database.
2. Select the database and choose Create - <form name>.
3. Fill in all the fields and save the document.

Chapter 3: Designing Forms 63


4. Repeat steps 2 and 3 to create several documents with different field
values.
5. View the documents in all appropriate views.
6. Test all form actions.
7. Make any necessary design changes. When the form shows no
problems, close and save the form.
8. Copy the tested form to the live database.

64 Application Developers Guide


Chapter 4
Designing Fields

This chapter describes how to create fields to hold specific types of


information.

About fields
Fields are the individual elements on a form that store data. Fields
determine what data a single document can contain. Each field in a
document stores a particular kind of data, such as text, numbers, dates, or
user names. Often users can enter and edit field values, but sometimes data
is filled in or changed automatically.
The contents of a field can be displayed in documents and views or can be
retrieved for use in formulas. A field can be defined for use on a single form
or can be defined to be shared among multiple forms in a database.
A field definition has five elements: a name, a data type, a computed or
editable attribute, display options, and formulas or scripts associated with
the field.

About assigning data types for fields


Before you create a field, decide what type of data it will contain. Fields can
contain text, graphics, lists, or numbers. The type of field you create
determines the type of data the field can hold.

Text
Create a text field to hold letters, punctuation, and spaces, as well as
numbers that are not used in calculations, such as postal codes and phone
numbers.
Create a rich text field to hold pictures, graphs, hotspots, attachments, and
embedded objects. Also, use rich text fields to hold text, the font and color
of which you want to change and/or style with bold, italics, and
underlining.

65
Create a keywords field to hold lists of predefined text choices. Presenting a
list of choices to users makes data-entry easy and ensures that field values
are consistent.

Numbers and Formulas


Create a number field to hold numbers that you will use in mathematical
formulas. Number fields can hold the characters 0 1 2 3 4 5 6 7 8 9 - + . E e

Times and Dates


Create a time field to hold time and date information that appears as letters
and numbers separated by punctuation.

Authors and Readers


Create an Authors field to hold a list of user names, group names, and
access roles. Use Authors fields to give users who have Author access in the
database access control list the right to edit the documents they create.
Doing this means you dont have to expand their database access to Editor
access. Create a Readers field to limit the read access to a document to only
the users or groups listed in the Readers field.

Names
Create a Names field to display user or server names as they appear on
Notes IDs. Use Names fields to display names when you dont need to
assign access rights to documents. Use a Names field to display the creator
of a document or to maintain a list of users who edit the document.

About editable and computed fields


Every field is either editable or computed. If a field is editable, a user can
enter or change the contents of the field. If a field is computed, a formula
calculates the field value. Users can edit the contents of text, rich text, and
keywords fields. Users cant change the values in a computed field.
Number, time, authors, readers, and names fields are usually computed.

Editable field formulas


You can write up to three formulas for an editable field:
The default value formula provides an initial value that the user can
change.
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.

66 Application Developers Guide


The input validation formula checks the contents of a field against
predefined criteria, making sure the entry meets certain requirements.

Computed field formulas


Computed fields are often used to automatically enter data such as, the
authors name or the date in a field. There are three types of computed
fields. Which you choose depends on when you want the field calculation
to occur.

Computed
Create a computed field to hold a formula that you want to recalculate each
time a user creates, saves, or refreshes a document. After you create the
field, you write a formula to calculate the field value, which is stored with
the document.

Computed when composed


Create a computed-when-composed field to hold a formula that you want
to calculate only once when the user first creates the document. Use this
type of 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.
After you create the field, you write a formula to calculate the field value,
which is stored with the document and never recalculated.

Computed for display


Create a computed-for-display field to hold a formula that you want to
recalculate each time a user opens a document. Use this type of 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.
After you create the field, you write a formula to calculate the field value,
which exists only during the current session and is not stored for future
use. You cannot display the contents of a computed-for-display field in a
view.

Chapter 4: Designing Fields 67


About field names and labels
A label is optional descriptive text that appears on a form. A field name is a
required element for defining a field and never appears on a form.
Label text describes the field and appears on the form for the user to see.
Label text always appears the same for documents created with the form.
Use labels that describe the general purpose of the fields, such as To, From,
Author, Subject, Category, and Date.
If several forms in a database contain similar information, use the same
field names on forms whenever possible. This makes sharing information
between forms easier as you continue to develop the application.
Establishing and maintaining naming standards simplifies database design
throughout your organization.

About predefined fields with built-in functionality


Notes provides predefined fields that you can use to automatically add
functionality that you would otherwise have to program yourself. The
names of these fields are reserved by Notes. If you try to use a reserved
name differently or redefine the field, Notes displays an error message.

68 Application Developers Guide


Reserved fields for mailing documents
Reserved field name Use
MailOptions Gives users the option of mailing a document
SaveOptions Controls whether documents are saved when
mailed
Sign Signs creators name to prevent tampering
Encrypt Encrypts mail
SendTo Sends mail to users listed in field
CopyTo Sends copy to users listed in field
BlindCopyTo Sends blind copy to users listed in field
DeliveryPriority Delivers mail high, medium, or low priority
DeliveryReport Returns a report when mail is delivered to
recipient
ReturnReceipt Returns a receipt when recipient reads mail
MailFormat Routes mail via cc:Mail

Reserved fields for general use


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

About standard fields used in Notes templates


The following fields are frequently used in the templates that ship with
Notes. You may want to follow the same standards in databases you design
to maintain consistency and make it easier to share information between
forms.
Body an editable rich-text field that stores most of the information in a
document.
ComposedDate a hidden, computed-when-composed Time field that
uses the formula @Created.
From a computed-when-composed Authors field that uses the formula
@UserName.

Chapter 4: Designing Fields 69


Subject an editable text field that contains a one-line document
summary.

Creating a field
The field name is surrounded by a rectangle. You can use tabs, returns, and
other formatting tools to refine the fields position.
1. Open the form in Design mode.
2. Place the insertion point where you want the field to appear.
3. Choose Create - Field.
4. In the Field Properties box, assign a name to the field.
5. Assign a data type and select Editable or a computed option.
6. (Optional) Click the form and type a text label next to or above the
field.
7. (Optional) Highlight the label and choose Text - Text Properties to
change the text style.

Details
You assign field names, and Notes uses them to recognize and classify
fields. 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.
Since field names cannot contain spaces, run multiple words together for
example, ModifiedDate or separate them with an underline
Modified_Date. The Designer templates use the convention of an initial
capital letter followed by lowercase letters for example, SendCopyTo.
Renaming a field
Unlike forms and views that can have synonym names, a field can have
only one name. Renaming a field has the same effect as deleting a field from
a form. Rename fields only if absolutely necessary.
Renaming single-use fields
After renaming the field, 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 data to the new field name and to computed fields.
Copying fields
If you copy a field from the same form, each additional 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.

70 Application Developers Guide


Creating a field in a layout region
Placing a field in a layout region allows you to display the field value over
text or graphics. In addition, you have more display options for fields
containing lists in a layout region.
1. Open the form in Design mode.
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.
6. (Optional) To create a label for the field, choose Create - Layout Region
- Text.
7. Click the text area, choose Design - Object Properties, and type a field
label in the Text box. Click the green check mark.
8. Drag the text area above or to the left of the field and drag it to the size
you want.
9. Click the Style tab (the AZ icon) to change the text style for the label.
Details
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.
Creating certain date/time fields in a layout region automatically displays
calendar controls.
Creating an editable time field in a layout region with Show:Date
displays a calendar pop-up that allows the user to reset the date by
clicking on the calendar control and choosing a new date.
Creating an editable time field with Show:Date and time or
Show:Today specified displays a time control that users can set by
clicking the time control and sliding the selection bar to a new time. To
make the time control a duration control that displays an editable range
of time, specify that the field can allow multi-values. Then on the
Options tab, choose Separate values when users enter Blank Line.

Chapter 4: Designing Fields 71


About shared fields
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 the field once and reuse
it. When you define a field as a shared field, Notes displays the field with a
dark border to visually mark it as shared and adds the field name to a list
of shared fields available for use in a database. Then to insert a field 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.

Copying a shared field


Cutting and pasting converts a shared field to a single-use field. To revert
to a shared field, delete the single-use field and insert the shared field into
the form again.

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.

Creating a shared field


1. Select the database and choose Create - Design - Shared Field.
2. Give the shared field a name and click the green check mark to confirm.
3. Assign a field type and choose Editable or a computed option.
4. Click the shared field window, then save the field.
To copy a shared field from another database, copy the field, then click
Design - Shared fields in the navigation pane of the destination database
and paste the field into the view pane.

72 Application Developers Guide


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

Details
You cannot convert fields in a layout region.

Using a shared field


1. Open the form in Design mode.
2. Place the insertion point where you want the field to appear.
3. Choose Create - Insert Shared Field.
4. Select the shared field you want to use and click OK.
5. (Optional) Type a text label next to or above the field.
6. (Optional) Highlight the label and choose Text - Text Properties to
change the text style.

About displaying text


There are several ways to display text in a document. To display static text
that is, text you want to appear on every document enter the text
directly on the form and use style options to enhance the appearance.
Although you can use a layout region to control the look and placement of
text on a form, keep in mind that layout regions do not work in
Web-enabled applications.
To display text in a field, create a text field or a rich text field. A text field
displays user-generated or computed text values. Text fields generally
suffice for data entry or text output in an application.
To hold or display large amounts of text, however, use a rich text field. A
rich text field can be used anywhere except in a layout region. A rich text
field is subject to the size limitations imposed on other field types. In
addition to text, rich text fields can also contain graphics, attachments, and
objects. The Body field in a mail document is a rich text field.

Chapter 4: Designing Fields 73


Creating a field to display text
To display plain text
1. Open the form in Design mode.
2. Create a field or click an existing field, and then choose Design - Field
Properties.
3. Select Text as the data type.
4. If you dont want users to change the value, select a Computed option.
5. To generate editable or computed field values, click the design pane,
select a formula type, and write the formula. Click the green check
mark to save the formula.
6. Close and save the form.

To display styled text in a rich text field


1. Open the form in Design mode.
2. Create a field or click an existing field, and then choose Design - Field
Properties.
3. Select Rich Text as the data type.
4. Close and save the form.

About displaying lists of choices


To present or gather information, display a list of choices to a user. The list
can be generated by formula or entered as part of a field definition. To
format a list, use a set of check boxes that allow users to select multiple
choices or use a set of radio buttons that limit users to one item in the list.
The items in the list are called keywords.

Generating choices for a list


Choose one of these options for generating keywords.
Enter choices (one per line)
Type a list of keywords in the formula window. Enter one keyword per
line in the edit box and select Sort to display the list in alphanumeric
order. Click the green check mark to save your entries.
Notes stores keywords as text, but keywords can contain numbers and
punctuation characters.
Use formula for choices
Type a formula in the formula window to generate a list of keywords.
Click the green check mark to save your entries.

74 Application Developers Guide


Use Address dialog for choices
This option displays the Names dialog box so users can select names
from a Personal or Public Address Book. 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.
Use Access Control list for choices
This option brings up a list of people, servers, groups, and roles in the
access control list for the database.
Use View dialog for choices
This option brings up a dialog box containing entries from a column in
a view. Select the database to look up, select a view, and select a
column number.
Looking up values in a view lets you retrieve data from databases. This
is convenient for displaying keywords that change, such as customer
names, sales territories, and job titles.
View lookups provide the following benefits:
Non-designers can maintain keywords without having access to the
rest of the database design.
Designers can avoid hard-coding keywords into fields, this makes
verification and maintenance easier.
Designers can hide the design of the database without affecting
maintenance of keywords.
Designers or administrators can customize the application or
conveniently translate lookup information to other languages.
Users can review keywords and codes more conveniently from
outside the form or application.
Note Use lookups sparingly because they adversely affect the
performance of the application.
To retrieve information from non-Notes databases or to create more
complex lookups, use @DbColumn and @DbLookup in formulas
instead.
For more information on @DbColumn and @DbLookup, see the
Programmers Guide.

Chapter 4: Designing Fields 75


Creating a field to display a list of choices
To present users with a list of choices, create a keywords field.
1. Open the form in Design mode.
2. Create a field or click an existing field, and then choose Design - Field
Properties.
3. Select Keywords as the data type and select Editable or a computed
type. (Most keyword fields are editable.)
4. To create editable or computed field values, click the design pane, select
a formula type, and write the formula; click the green check mark to
save the formula.
5. Select a Choices option to determine how keywords are generated and
write the list or formula, or select the options appropriate to the choice
you selected.
6. Click the Display tab (the second tab) and select an Interface style.
7. (Optional, available for dialog lists) Select Dont 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 keywords.
8. (Optional) If other formulas in the document are dependent on the
value of the keywords field, select Refresh fields on keyword change.
9. (Optional) To refresh the keyword list each time the document is
refreshed, select Refresh choices on document refresh.
10. (Optional) If available for the interface style you selected, click the
Basics tab and select Allow values not in list to let users add their
own keywords without changing the original list.
11. (Optional) If available for the interface style you selected, click the
Basics tab and select Allow multi-values to allow several keywords in
the field.

Details
Allowing user-defined keywords and multiple values
Select Allow values not in list (not available for all types of keywords) to
let users enter their own keywords. With most of the interface choices, you
can also select Allow multi-values to let users choose more than one
keyword. Multiple items are stored as a text list. If these properties arent
selected, users are limited to one selection from the set of predefined
keywords.

76 Application Developers Guide


Refreshing fields when keywords change
This property 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.
Display options for keyword lists
Dialog list (not available in layout regions)
Users either press ENTER or click the entry helper button to see all the
keywords at once, press the space bar to display keywords one at a
time, or type a letter to display the first keyword beginning with that
letter.
You can also select Allow values not in this list, although users new
entries are not added to the list for future use. Multiple values are
accepted only if Allow multi-values is set for the field. You can also
select Dont display entry helper button to disable the button next to
the field.
Checkbox
Each keyword is displayed as a box; users click one or more keywords
to fill in the field. The Allow values not in this list property is not
applicable to check boxes.
Check boxes have frame and column options. To create a wide check
box panel, choose a column number between 2 and 8.
Radio button
Each keyword is displayed with a button; users can click only one. The
Allow multi-values and Allow values not in this list properties are
not applicable to radio buttons.
Radio buttons have frame and column properties. To create a wide
button panel, choose a column number between 2 and 8.
Listbox (available only for keywords fields in layout regions)
Each keyword is displayed with an expanded list box. Users click an
entry to select it, or if Allow multi-values is selected for the field,
users can click more than one entry. The Allow values not in this list
option is not available.
List boxes have frame, size, and placement options. To resize the list
box without dragging it, change the Width and Height measurements.
To move the list box in the layout region without dragging it, change
the Left and Top measurements.
Combobox (available only for keywords fields in layout regions)
Each keyword then is displayed with a drop-down list box. Users click
the drop-down arrow to see the entries, and click the one they want.

Chapter 4: Designing Fields 77


The Allow multi-values and Allow values not in this list properties
are not applicable to combo boxes.
Combo boxes have frame, 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.

Examples
You want to make it easy for users to include a product number when they
fill out a Purchase Request. You create an editable keywords field named
ProductNumber and use the 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 keywords 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;Loca
tion=Far East;Japan:Singapore:South
Korea;Location=North America;Canada:Mexico:United
States;)

About creating synonyms for choices in a list


You can create synonyms for keywords, so that if the keyword itself
changes, any formula referencing the synonym still works. You can also
create short synonyms for long keywords to keep formulas more concise.
Keyword synonyms are also useful if your database is to be translated,
since only the keywords themselves need be translated and formulas dont
need to be rewritten. Enter the keyword synonym using | followed by the
synonym. For example, A is the synonym for All in this entry:
All | A
If you use keywords synonyms, the leftmost name is displayed in the
document, but the rightmost name is stored internally.
Note Column formulas that refer to keywords fields use the synonym
names in the view, not the keywords that users see in documents.

Converting keyword synonyms to full category names


If you base a categorized column on a keywords field that contains
synonyms for the keywords, synonyms are used as the category names.

78 Application Developers Guide


For example, a RequestType field that contains the following keywords
displays the category names as HW, SW, and SVC:
Hardware Request | HW
Software Request | SW
Service Request | SVC
To display the full names as category names, use a hidden field or column
formula that converts the synonyms back to their full names:
@If(RequestType=HW;Hardware Request;RequestType=SW;
Software Request;Service Request);

Example: Using keywords synonyms


You want Service Repair Requests to have a field for product groups. You
create an editable keywords field called Product and select Enter choices
(one per line). You include keyword synonyms, so that if the product
groups change, any formula referencing the synonym still works. You enter
this keywords list:
Microwaves | 1
Ovens | 2
Refrigerators | 3
Specialty Items | 4
Toasters | 5
Columns that refer to keywords fields use the synonym names in the view,
not the keyword 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 synonym name to its long form:
@If(Product=1;Microwaves;Product=2;Ovens;Product=3;
Refrigerators;Product=4;Specialty
Items;Product=5;Toasters;Product=;;);

Displaying graphics, attachments, and objects


You can use a rich text field anywhere except in a layout region. Such fields
can contain large amounts of data and are not subject to the size limitations
imposed on other field types. Rich-text fields are often used in Web-enabled
applications to display HTML formatted text, as well as to display graphics,
styled text, and objects.
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.

Chapter 4: Designing Fields 79


You can use a rich text field to launch an OLE object that is, to open an
object from another application within a Notes form. You can even define
the field so that an OLE object automatically launches when a user opens
the form.

About displaying graphics, attachments, and objects


You can use a rich-text field anywhere except in a layout region. Such fields
can contain large amounts of data and are not subject to the size limitations
imposed on other field types. Rich-text fields are often used in Web-enabled
applications to display HTML formatted text, as well as to display graphics,
styled text, and objects.
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.
You can use a rich-text field to launch an OLE object that is, to open an
object from another application within a Notes form. You can even define
the field so that an OLE object automatically launches when a user opens
the form.

About displaying numbers or currency


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 example above, the Monthly Total field is
computed so users cannot edit the value.

Creating a field to display numbers or currency


1. Open the form in Design mode.
2. Create a field or click an existing field then choose Design - Field
Properties.
3. Select Number as the data type; then choose formatting options.
4. Select a Computed option if you dont want users to change the value.

80 Application Developers Guide


5. To generate editable or computed field values, click the design pane,
select a formula type, and write the formula; click the green check mark
to save the formula.
6. Close and save the form.
Note Fields used in calculations must have default values. Otherwise, the
message Incorrect data type for operator or @Function: Text expected
appears.

Details
Choose any of these number formats:
General displays numbers as they are entered; zeroes to the right of the
decimal point are suppressed. For example, 6.00 displays as 6. The
default thousands separator is based on the type of measurement
(Imperial or Metric), which users set in the international User
Preferences.
Fixed displays numbers with a fixed number of decimal places. For
example, 6 displays as 6.00 when 2 is selected in the Decimal Places
list.
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 a currency symbol. For example, $15.00
is displayed when the value is 15 and 2 is selected in the Decimal
Places list. The currency symbol is determined by the international
settings of the users workstation.
Notes recognizes the following formats for numbers:
Integers 123, -123
Decimal fractions 1.23, 0.12, -.12
Scientific notation 1.23E2, -1.23E12
Currency $2.50, ($600.09)
Notes can store numbers from 2.225E-308 to 1.798E308 with 14-digit
accuracy.

Chapter 4: Designing Fields 81


About displaying dates and times
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 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 Time field showing Use the formula
Date a document is created Date and time @created
Date a document is Date and time @modified
modified
Current date Date @today
Current date and time Date and time @now

Understanding valid entries in time fields


Dates may range from 1/1/0001 through 12/31/9999. To specify a date that
is not in the twentieth century (any date not in the 1900s), users must
specify all four numbers of the year for example, 12/31/2010.
Times may range from 00:00:00 through 23:59:59 in the 24-hour format and
from 12:00:00 A.M. through 11:59:59 P.M. in the 12-hour format.
When reading or displaying dates, Notes uses the default date separator
a slash (/) or a hyphen (-) for the platform where the database is stored.

Creating a field to display dates and times


1. Create a field and choose Design - Field Properties.
2. Select Time as the field type.
3. Choose display options to specify how to display the date and time.
4. Choose format and time zone options.
5. To generate editable or computed field values, click the design pane,
select a formula type, and write the formula; click the green check mark
to save the formula.
6. Close and save the form.

Details
The following are valid date and time formats:
10/30
10/30/95
Today

82 Application Developers Guide


Yesterday
10/30 11:00 P.M.
10/30/95 11:45:30 A.M.
11:00 P.M.
11:45:30 A.M.
11:45:30 A.M. Today
Displaying dates and times in a layout region
Creating certain date/time fields in a layout region automatically displays
calendar controls.
Creating an editable Time field in a layout region with Show:Date
displays a calendar pop-up that allows the user to reset the date by
clicking on the calendar control and choosing a new date.
Creating an editable Time field with Show:Date and time or
Show:Today specified displays a time control that users can set by
clicking the time control and sliding the selection bar to a new time. To
make the time control a duration control that displays an editable range
of time, specify that the field can allow multi-values. Then on the
Options tab, choose Separate values when users enter Blank Line.
Time zone options
Choose any of these time zone options:
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 P.M. 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 P.M.
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. If the document was created
in Boston at 3:00 P.M., the user in Los Angeles sees the creation time as
3:00 P.M. 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.

Chapter 4: Designing Fields 83


If the document was created in Boston at 3:00 P.M., users in the U.S.
Eastern standard time zone see the creation date as 3:00 P.M., while users
in other time zones see the creation date as 3:00 P.M. EST.

Examples
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 computed-when-
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.
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]).

84 Application Developers Guide


About creating fields that inherit values
A field can inherit values from another document or from another field on
the same document. To inherit the values from another document, a user
highlights the parent document and then creates the document that will
inherit the values. The documents do not need a main document/response
document relationship. The highlighted document is assumed to be the
parent document. The field that inherits data does not have to use the same
name as the parent field, although doing so enables designers to see the
connection between the two forms. To suppress inheritance, press CTRL
while choosing Create.
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 its parent field. The formula
must use the parent fields name. The form itself does not need the Inherit
field values property set.

Inheriting information from a main document


A response document automatically inherits the subject of the main
document and adds text that distinguishes it from the original subject line.
The Subject field of the Response form uses the formula
Response to + Subject

Inheriting address information


In a Customer Contacts database, 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 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.

Creating a field that inherits values from another document


To save users from unnecessary typing or to keep related documents
consistent, fields can inherit information from another document.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. (Optional) Click the Defaults tab. To display the parent document in the
preview pane, select On Open: Show context pane and select Parent.
4. Select On Create: Formulas inherit values from selected document.

Chapter 4: Designing Fields 85


5. Create the fields that should inherit values.
6. 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.
7. Close and save the form.

Creating a field that inherits an entire document


To clarify a new documents association with another document, create a
field that inherits the full contents of a users selected document. For
instance, a field in a new response document can automatically inherit the
contents of its main document.
1. Open the form in Design mode.
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. Select the new rich-text field and select a document display option.
7. Close and save the form.
Details
To inherit the values from the parent document, a user highlights the
document before choosing Create - form_name. The documents do not need
a main document/response document relationship. The highlighted
document is assumed to be the parent document. To suppress inheritance,
press CTRL while choosing Create.
Displaying the parent document in a collapsible section gives users the
opportunity to review the parent document, but doesnt clutter the form.
Rich text inherits the fully expanded contents of the parent document.

86 Application Developers Guide


About creating 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. Using this special
field is more flexible than assigning version control to a form, which affects
every document created with the form.
1. Create a field named $VersionOpt and define it as a computed text or
editable keywords 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 keywords field, select Enter choices (one per line) and write
each entry, using a keyword and its equivalent synonym for
example, Save as response automatically | 2.
3. Click the design pane, click Formula, and write a formula.
4. For a computed field, add a formula; for an editable field, add a default
value formula.
A computed text field
A computed $VersionOpt field can contain the following values:
Value Type of tracking
0 No version tracking
1 New versions become responses if users choose File - Save As
New Version when they save a document
2 New versions automatically become responses when saved
3 Prior versions become responses if users choose File - Save As
New Version when they save a document
4 Prior versions become responses when saved
5 New versions become siblings if users choose File - Save As
New Version when they save a document
6 New versions automatically become siblings when saved

An editable keywords field


To make the choices easier to understand in an editable keywords field, use
the required values as synonyms and insert a more readable name in front
of each, followed by a | (vertical bar). For example:
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

Chapter 4: Designing Fields 87


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

About displaying user names


Create a Names field to display user names as they appear on Notes IDs
for example, Betty Powers/WorkSavers/US, instead of Betty
Powers=CN/Worksavers=O/US=C.
For example, to display only the common name portion of names, in a
Members field use this input translation formula in an editable Names field:
@Name([CN];Members)

Creating a field to display user names


1. Open the form in design mode.
2. Create a field, or click an existing field then choose Design - Field
Properties.
3. Select Names as the field type.
4. Select Editable to allow authors and editors to type or choose a name.
5. Select Computed if you want to write a formula to compute the field
value.
6. To create editable or computed field values, click the design pane, select
a formula type, and write the formula; click the green check mark to
save the formula.
7. Select a Choices type, other than None, to look up names in the
Address Book, access control list, or view dialog.
8. (Optional) Select Allow multi-values to allow more than one name to
be stored in the field.
9. (Optional) Select Allow values not in list to allow users to enter
additional names.

88 Application Developers Guide


About looking up names for field values
To help users enter names correctly in a document, provide links to existing
lists of names. For example, an Authors 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 who can be
names in the field. Other sources for names are the Public Address Book or
a view dialog that presents names from a column in a view.
Lookup options are available when you create a Names field, an Authors
field, and a Readers field.
You can turn off this option by maintaining the default of none. If you
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
None
If you select None, you rely on a formula or on authors to create the list of
names.

Use Address dialog for choices


This option displays the Names dialog box so users can select names from a
Personal or Public Address Book. 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.

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 the Database
Managers Guide.

Chapter 4: Designing Fields 89


About writing formulas for fields
You can write up to three formulas for each editable field:
The default value formula provides an initial value that the user can
change.
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.
The input validation formula checks the contents of a field against
predefined criteria, making sure the entry meets certain requirements.
You write only one formula for each computed field. The formula defines
the field value.

Where you write a field formula


You enter field formulas in the formula pane that appears when you design
a form. First, choose the event for which you are providing the formula. For
example, the default value event provides an initial value for the field.
Then, enter the formula in the formula pane.
Use the Fields & Functions and @Commands lists in the formula pane
as shortcuts for looking up field, function, and command names and for
pasting them into the formula.
For information on writing formulas for fields, see Chapter 1 of the
Programmers Guide.

Creating a default value formula for a field


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.
1. Create an editable field, and choose Design - Field Properties.
2. Select Event: Default Value in the design pane.
3. Write one of the following in the edit window:
A formula
A field name
A text string in quotation marks
4. Click the green check mark to save the formula.
For more information on writing field formulas, see the Programmers Guide.

90 Application Developers Guide


Details
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
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.
For information on writing formulas for fields, see Chapter 1 of the
Programmers Guide.

Examples
The default value formula can provide a value or use a formula to calculate
one. For example:
The formula Returns
0 The number 0
@Now The current time and date
@Name([CN;@Username) The common name portion of a users
hierarchical name
Price 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

Creating an input translation formula for a field


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.
1. Create an editable field and choose Design - Field Properties.
2. Click the design pane, select Event: Input translation, and write a
formula.
3. Click the green check mark to save the formula.
For more information on writing input translation formulas, see the
Programmers Guide.

Chapter 4: Designing Fields 91


Examples
This 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);
This 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));
For information on writing formulas for fields, see the Programmers Guide.

Creating an input validation formula for a field


Create an input validation formula to verify that the information users enter
in a field meets criteria you specify or to ensure that users fill in a required
field. Input validation formulas are evaluated each time a document is
saved, recalculated, or refreshed. Alternatively, you can write a script based
on the Exiting event to verify or require information.
1. Create an editable field and choose Design - Field Properties.
2. Select Event: Input Validation in the design pane.
3. Write a formula in the edit window using @Failure and @Success.
4. Click the green check mark to save the formula.

Details
@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.
The following illustrate two common uses for an input validation formula:
Field criteria Formula
User must enter a value that is less @If(Cost<100;@Success;@Failure(Cost must
than 100 in Cost field be less than $100.));
User must enter a value for the @If(Subject = ; @Failure(You must enter a
Subject field subject for your document.); @Success)
For information on writing formulas for fields, see Chapter 1 of the
Programmers Guide.

92 Application Developers Guide


About writing formulas for computed fields
Computed fields require formulas to supply their values. For example, you
use a computed field to assign a creation date to a document. A formula
can be as simple as a text string that you assign to the field by entering it in
the formula pane.
Computed fields are normally recalculated when users create documents,
choose View - Refresh Fields, press F9, or save documents. Selecting
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 it is filled in by selecting Automatically
refresh fields for the entire form. 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.
For information on writing formulas for fields, see Chapter 1 of the
Programmers Guide.

Calculating a value for a computed field


1. Create a field, or click an existing field. Then choose Design - Field
Properties.
2. Select any type except Editable.
3. Select Event: Value in the design pane.
4. Write a formula, a field name, or a text string in quotation marks in the
edit window.
5. Click the green check mark to save the formula.
6. (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 Basics tab.
7. (Optional) To recalculate field values while users edit a document, click
the form and choose Design - Form Properties, click the Defaults tab,
and select Automatically refresh fields.
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 Chapter 1 of the
Programmers Guide.

Chapter 4: Designing Fields 93


Examples
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;
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 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 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);

94 Application Developers Guide


adjust := @If(((wkday + @Modulo(temp; 7) - 7) > 0); 2; 0);
working_days := temp - (weekend_days + adjust);
@If(Currentdate = ; 0; working_days);

About improving the run time of formulas and scripts


When possible, replace long @function formulas with shorter,
well-designed LotusScript programs to improve processing time.
Use LotusScript front-end UI classes only for form navigation and other
user-interface simulations. Use the back-end database classes for data
manipulation. The back-end classes are faster than @functions or
front-end classes.
For more information, see Using the Notes classes in Chapter 3 of the
Programmers Guide.
When doing lookups with @functions, use @Prompt to prompt the user
to enter information that will narrow down the search.
Use @Sum to add a set of numbers or number lists and return the total.
Plan and design lookups to external data sources with performance and
response time in mind. It may be better to have a well-synchronized
movement of data than to require frequent or time-consuming external
lookups. Consider internal database issues such as timing, data format,
data type, and lags imposed by external systems.
For more information on formulas and scripts, see the Programmers Guide.

About automatically refreshing field values


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.
Manually, when a user manually refreshes a document.
For better performance on large documents with many computed fields, do
not select the form property Automatically refresh fields. Instead,
recalculate specific fields. Use the Refresh field on keyword change for a
keyword field, or write a LotusScript field event to recalculate the
document or update other fields when users move from a specific field.

Chapter 4: Designing Fields 95


Designing a form that refreshes field values automatically
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.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Click the Defaults tab.
4. Select Automatically refresh fields.
5. Close and save the form.

Making a field to display multiple values


Any type of field, except rich text fields and some types of keywords fields,
can hold multiple values. For example, you might have a field for collecting
the names of field offices in your organization. The values from such fields
can also be displayed in columns.
1. Create a field with any data type other than Rich Text.
2. Select Editable or any computed type.
3. Select Allow Multi-Values.
4. Click the Options tab if you created any field other than a keywords
field.
5. Click one or more punctuation choices for Separate values when user
enters, to allow users to separate entries as they wish.
6. Select one Display separate values with punctuation choice to specify
how entries appear.

Details
Use New Line and Blank Line separators for display separators to make
multiple entries easy to read.
To align and separate multiple values on the form, use the ruler
(CTRL+R) to create a hanging indent where the field begins. Select New
Line for both the input and display separator.

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.

96 Application Developers Guide


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 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. Click the Options tab.
3. Select Give this field default focus.

About hiding fields


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

Hiding options
You can hide a field and any other 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 keywords field, can
be hidden during editing.
The following are options for hiding fields:
Hide from Notes client
Information is hidden when the application opens on a Notes
workstation.
Hide from Web Browsers
The information is hidden when the application opens on a Web
browser.
Previewed for reading
The hidden information isnt visible when users read documents in the
preview pane.
Previewed for editing

Chapter 4: Designing Fields 97


The hidden information isnt visible when users work on documents in
edit mode in the preview pane.
Opened for reading
The hidden information isnt visible when users open documents in
read mode. A field that cant be read cant be printed.
Opened for editing
The hidden information isnt visible when users work on documents in
edit mode.
Printed
The hidden information isnt visible on printed documents.
Copied to the Clipboard
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.
Hide paragraph if formula is true
A formula determines the circumstances in which information is
hidden.

Hiding 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 and any related text or buttons you want to hide.
2. Choose Text - Text Properties.
3. Click the Hide tab.
4. For basic options, select Hide paragraph when document is: and click
all situations when users dont need to see the field information.
5. For programmer options, select Hide paragraph if formula is true
and write a formula in the formula window 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
Programmers Guide.

Details
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.

98 Application Developers Guide


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 keywords field that displays these radio button
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.

About deleting fields


To delete a field, you select the field on the form and press the Delete key or
choose Edit - Clear. To delete a shared field, you select the shared field
from the list of shared fields and choose Edit - Clear. Deleting a single-use
or shared field can have consequences in your application.
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;

Chapter 4: Designing Fields 99


Deleting a shared field
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
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.

About fields that prompt users to select folders


Adding a FolderOptions field to a form allows users to 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 or
numbers field or an editable keywords 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 keywords field, select Enter choices (one per line) and write
each entry, using a keyword and its equivalent synonym for
example, Save in current folder | 2.
3. Click the design pane, click Formula, and write a formula. For a
computed field, add a formula; for an editable field, add a default value
formula.
Details for a computed text field
For a computed text field, the FolderOptions field must contain the value 1
or 2.
1 (Prompt user to choose folder)

100 Application Developers Guide


This value prompts the user with the Add to Folder dialog box. If a folder is
open, that folder is selected by default. If a view is open, Folders and Views
are selected. 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)
This value adds the document to the open folder.
Details for an editable keywords field
To make the options easy to understand in an editable keywords field, use
the required values as synonyms and insert a more readable name in front
of each, followed by a | (vertical bar). For example:
Choose a folder | 1
Save in the open folder | 2

Chapter 4: Designing Fields 101


Chapter 5
Designing Views

This chapter describes how to design views that 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.

About designing views


Views are the entry point to the data stored in a database. Users open a
view to see a list of documents in the database and then open documents
from there. Every database must have at least one view, although most
databases have more than one view.

Standard views
A standard outline view acts like a table of contents for a database and is
the most common type of view. It organizes documents in rows and
columns. Rows display selected pieces of information from one document.
To open a document, Notes users double-click a row; Web users click a link
in one of the columns.
These screens compare how a Discussion view as it appears to both
Netscape Navigator users and Notes users.

103
Calendar views
A calendar view groups documents within date blocks. 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,
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.

104 Application Developers Guide


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. In a
discussion database, you might use a column 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.

About shared views


Views are either shared views available to many users or personal views
used by one person. You designate the view type when you create it and
cannot change it later.

Shared views
Shared views are views that are available to any users 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.

Shared, personal-on-first-use views


Shared, personal-on-first-use 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.
After a user saves a shared-to-personal 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 personal version of the view wont see the new
column. To obtain design changes, users must delete their personal versions
of the view and open the shared-to-personal view again.
Shared-to-personal views are not a security measure, as they do not protect
data. If you create a shared-to-personal view that omits certain documents,
a user can still create a personal view that includes them.
Shared-to-personal 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.

Chapter 5: Designing Views 105


Personal views
Users can create personal views to organize documents in personalized
ways by choosing Create - View.
If a user has rights to create personal folders/views in the access control
list, personal views are stored in the database. If the user does not have the
access control list right to create personal forlders/views, personal views
are stored in the users personal workspace file (DESKTOP.DSK).

About designing folders


Folders have the same design elements as views. You 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.
For more information about folders, see Notes Help.

About naming a view


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

Naming tips
Views appear in alphabetical order in menus and lists. To force names
to appear in a different order, number or letter them.
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.

About alias names


An alias is an internal name for a 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.

106 Application Developers Guide


You can append more than one alias name by entering the | (vertical bar)
symbol followed by the alias name. Always keep the original alias as the
rightmost name.
Main View | View1

Changing a view name


You can edit the view name or alias name in the View Properties box when
the view is open in design mode. 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:
Nach Premierendatum
and keep both By Screening Date and DateView as aliases:
By Screening Date | DateView

Naming techniques
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 folders pane.
For other ways to hide views, see About hiding a view later in this
chapter.

Shortcut keys
The shortcut (an underlined letter) is easy to see on the View menu because
its the first letter of the name, and Windows, OS/2, and UNIX users can
type the letter to select the view. 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. This can result in shortcuts that are difficult to see
and remember. For example, the shortcuts (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

Chapter 5: Designing Views 107


If you cant change the names, 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
If you dont want to overwhelm users with long lists or if you have related
views that should be grouped together, you can arrange them in a hierarchy
so that a group of related menu items are organized under one item in the
navigator pane. A user clicks on the higher-level name to display the
cascaded list.
If you didnt specify a cascading view when you created the 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

About 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
in design mode)
Not relevant to users

108 Application Developers Guide


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, set the Lines per heading
setting in the Style tab of the View Properties box to a number greater
than 1.
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.

Table of view and column styles


To make a view attractive and easy-to-use, consider the layout of the view
and its columns. Both view 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 Description Comments Location
View styles
Color: Background Determines the White, light blue, View Properties - S
background color and yellow are tab
for the view. good choices.
Collapse all when Displays the top Useful for large View Properties -
database is first level category in views with many Options tab
opened categorized views categories or
or the main topics. Not
documents in a applicable to
hierarchical calendar views.
responses view.
Users click the
category to see
individual
documents within
the category.
continued

Chapter 5: Designing Views 109


Option name Description Comments Location
Row styles
Lines per row (1-9) Determines how Shrink rows to View Properties - S
many lines a content and tab
column can Color: Alternate
contain. rows are useful
accompaniments to
multi-line rows.
Color: Unread Determines the Red is used for View Properties - S
rows color for unread unread documents tab
documents. in template
designs.
Color: Alternate Determines the Useful for View Properties - S
rows color that multi-line rows. tab
alternates with the Not applicable to
background color calendar views.
to highlight every
other row.
Show selection Shows the If you deselect View Properties - S
margin document selection Show selection tab
margin. Deselect margin, users can
for cleaner-looking still select
rows. 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.
Shrink rows to Keeps gaps from View Properties - S
content appearing below tab
rows that are
shorter than the
number of lines
per row you select.
continued

110 Application Developers Guide


Option name Description Comments Location
Row spacing Determines how More space makes View Properties - S
(Single, 1-1/4, much space there each row easier to tab
1-1/2, 1-3/4, is between rows. read. Less space
Double) condenses the view
contents to make it
useful for reports
or Web users.
Show twistie when Shows a green Not applicable to Column Properties -
row is expandable triangle next to a calendar views. Basics tab
column that
displays categories
or response
documents.
Extend last column Fills out the last View Properties - S
to window width column to avoid tab
empty space in the
view.
Column styles
Column width Determines how (Optional) Select Column Properties -
many characters fit Resizable to Basics tab
in one rows allow users to
column. change the width
as needed.
With the view in
design mode, you
can also click the
column and drag
the column divider
line to the width
you want.
Text style and Determines the Use Apply to All Column Properties -
color: Column title font, size, color, button to change Title tab
and alignment of the text style for all
an individual titles in the view.
column title at the
top of the view.
continued

Chapter 5: Designing Views 111


Option name Description Comments Location
Text style and Determines the Use Apply to All Column Properties -
color: Column font, size, color, button to change AZ tab
values and alignment of the text style for all
values that display columns that
in this column. display text in the
view.
Hide column The column title Useful for columns Column Properties -
and values do not used for sorting Basics tab
display to users. that contain values
users dont need to
see. This is not a
security feature.
Multi-value For any documents Useful for making Column Properties -
separator that display columns more Basics tab
multiple values in readable if they
the column, contain several
separates each values (usually
value with generated by a
punctuation or a multi-value field).
new line.
Show column Shows a bar at the Beveled View Properties - S
headings (Beveled, top of the view background is tab
Simple) with column titles gray.
with either a Simple
beveled or flat background
look. matches view
color.
Lines per heading Determines how Useful for long View Properties - S
(1- 5) many lines a column titles or tab
column title can instructions placed
wrap. in a column title.
Color: Column Determines the View Properties - S
totals color of the total tab
numbers for any
columns that
contain totals.

112 Application Developers Guide


Creating a view
You need Designer access or higher to create a shared view.
1. Select the database and choose Create - Design - View.
2. Name the view.
3. Click Shared.
4. Click Views to store the view at the top level, or click the name of
another view under which the new view should appear.
5. (Optional) To create a personal view and distribute it to users, select
Personal on first use and, if you wish, select Store in desktop to
save personal views in the users DESKTOP.DSK files rather than in the
database.
6. Click Options, click Blank, and click OK.
7. Click OK.
8. Double-click the new view in the Views list to open it in design mode.
9. Click the column labeled #, choose Edit - Clear, and Yes to confirm.
10. Choose Create - Insert New Column to create the first column.
11. Add other columns by either:
Choosing Create - Insert New Column to create a column to the left
of the highlighted column.
Choosing Create - Append New Column to add the column after all
existing columns.
12. Click each column and, in the design pane, add programming to
determine the column value.
13. In the design pane, select View Selection from the Define list and add
programming for the views document selection.
14. Choose Design - View Properties to style the view.
15. Click each column and choose Design - Column Properties to style the
column.
16. Close and save the view.

Other view design procedures


To open a view in design mode, choose View - Design, click Views, and
double-click the view name.
To copy a column, open the view in design mode, 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.

Chapter 5: Designing Views 113


To delete a column, open the view in design mode, click the column, and
choose Edit - Clear.
To copy a view, click Design - Views, click the view you want to copy,
choose Edit - Copy, then Edit - Paste.
To delete a view, choose View - Design, click Views, click the view name,
and choose Edit - Clear.

Converting a view to a calendar view


A calendar view style 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 time/date value and
choose a Sort option 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.

Details
If you select the column sorting option Show multiple values as separate
entries for the first column, documents display within multiple date
blocks. Otherwise, they display only in the first matching date block. 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 design mode. 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 design mode. 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.

114 Application Developers Guide


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.

About 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 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 selects only
particular documents. For example, in a task-tracking database, the Work in
Progress view could select only those documents whose Status field does
not contain Complete. In a brainstorming database, the Design Ideas
view could select all documents categorized as Design Suggestion.

Choosing the type of program


With a view in design mode, you program the document selection in the
design pane. Choose View Selection in the Define list box, click the button
for the type of programming you want to add, then build the program in
the window below.

Chapter 5: Designing Views 115


Easy
Easy allows you to create a document selection without knowing a
programming language. In the design pane, click Easy, then click Add
Condition for each selection you want to include. To delete a condition,
click it in the formula window, and choose Edit - Clear.

Formula
Formula allows you to create a program for document selection that uses
the @function formula language. In the design pane, click Formula and
write the formula in the window below.

Examples
Selecting documents by form name and field value
If a database contains an Action Item form and a Status field on that form, 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
selection formula is:
SELECT Form =Action Item & Status=Open
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

116 Application Developers Guide


Table of document selection conditions for views
When you click Easy as the Define: View Selection formula, you have these
selection options. You can combine multiple conditions to narrow down the
selection.
Condition Selection 1 Selection 2
By Author contains <author name> or choose from
does not contain Address Book
By Date date created is on
date modified 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
By Field <field name> contains
does not contain
<date field name> 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
<number field name> is equal to
is greater than
is less than
is not equal to
is between
is not between
By Form <form name> <field values> for multiple fields
By Form Used <form name>

Chapter 5: Designing Views 117


Details
Easy conditions
The Easy condition cant look for all the values in a multi-value field
because it reads any separators you enter as text; the condition determines
only whether a field contains one value.
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 Help and Making a field that allows users with
author access to edit documents in Chapter 4.
Selecting documents by date
The Date created condition selects documents based on the Created date in
the Document Properties box.
The Date modified condition chooses documents based on the Modified
date in the Document Properties box.
Selecting documents by field value
If the field is of type Text, Notes 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.

118 Application Developers Guide


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

About adding programming to columns


The values each column shows are generated by a program attached to the
column. The design pane gives you choices for adding programming to a
column. Click the column you want to program, click the button in the
design pane for the type of programming you want to add, then build the
program in the window below.

Simple functions
Simple functions allow you to add programming without knowing a
programming language. In the design pane, click Simple function and
choose the function you want. The default selection for a new column is #
in View which numbers documents according to their internal sequence.

Chapter 5: Designing Views 119


Field
Field allows you to populate the column with field values within
documents without writing a program. In the design pane, click Field and
choose the field whose value you want. This technique works only with text
fields because columns cant interpret other types of data without a
conversion formula that is, dates, rich text, or numbers or encrypted text.

Formula
Formula allows you to create a program for a column using the @function
formula language. This is useful when you need to process values in a
document first (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. In the
design pane, click Formula and write the formula in the window below.
Use the Fields & Functions button to paste fields, @functions, or
@commands into the formula. Column formulas can consist of a
combination of @functions, @commands, field values, and text enclosed in
quotation marks.
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
Determining text, based on a field value
You can show custom text in a column, based on various conditions for
example, whether sales were above a certain number. 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 Combined Mail (R4.6)
template uses the following formula to display a subject line that is
appropriate to the form with which the document was created:
@If(Form = NonDelivery Report; DELIVERY FAILURE: +
FailureReason; Form = Delivery Report; DELIVERED: +
Subject; Form = Return Receipt; RECEIVED: + Subject;
Form = ReturnNonReceipt; NOT RECEIVED: + Subject;
Subject)

120 Application Developers Guide


Combining text and dates
You can combine text and field values in a column in a scheduling database
to add more explanation about the documents. The formula below displays
a text message and a date, with two variations depending 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 only showing the month and
day portion of the date field 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))
Combining text and names
The following formula results in three possible results, based on the status
of the 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 -
Notes & Web (R4.6) template uses the simple function Creation Date, which
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 following formula separates
the two field values with a blank space:
Name + + Phone

Chapter 5: Designing Views 121


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 append 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.
@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 can be used with columns.
Function name Description
Attachment Lengths Displays the file size of document attachments. The
data type is a number list.
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 returned is a number.
Author(s) (Distinguished Displays document author name in hierarchical
Name) format, as in Denise Lee/Research/Acme.
Author(s) (Simple Name) Displays the document author name without its fully
distinguished format, as in Denise Lee.
continued

122 Application Developers Guide


Function name Description
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.
Creation Date Displays the time and date a document was created.
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.
Size (bytes) Displays the file size of documents.
# 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.
# of Responses (1 Level) Displays the number of direct descendant (response)
documents for a document or next-level
subcategories for a category.
# of Responses (All Levels) Displays the total number of descendant (response
and response-to-response) documents for a
document or subcategories for a category.

About 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 (R4.6) 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.

Chapter 5: Designing Views 123


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.
The graphics used in column icons cant be customized, but you can choose
from more than a hundred predefined column icons. 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
corresponding to the row in which the icons appear. 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.

124 Application Developers Guide


About 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.

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.

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.

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.

Chapter 5: Designing Views 125


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.

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.

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.

126 Application Developers Guide


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. In the Column Properties box for a user-sorted column, click
Secondary sort column and choose the secondary sort column and its
sorting order.

Character sorting rules


Domino sorts characters in this order:
Numbers
Letters
Accented letters
Punctuation/special characters
Sorting rules are also governed by these options:
Case sensitive sorting displays uppercase letters before lowercase
letters for example, A sorts before a.
Accent sensitive sorting sorts accented letters in the sorting order
appropriate to the language being used at the workstation.

About 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 that selects documents according to criteria you
specify in a formula as your sorting column.
For example, a Service Request form contains a Priority field, which uses
the following keywords 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

Chapter 5: Designing Views 127


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=Me
dium;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
Displays the value of the Priority field
Is not sorted

About 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 a 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: Change to view 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.

About adding categories to views


A view that displays categories enables users to find related documents. 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.

128 Application Developers Guide


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. A categorized column groups documents with matching values and
converts the 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.
Other options include:
(Recommended) Style the column text with a different color and in bold
face to make categories stand out.
(Recommended) Select the column style: Sort: Ascending or Sort:
Descending to organize the category names. (Sort: Ascending organizes
the categories in alphabetical order.)
(Recommended) Select the Basics view property Show triangles when
row is expandable to display a green triangle that users click to see
categorized documents.
(Optional) Select the Options view property Collapse all when
database is first opened to show only the category names when users
open the view.

About 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 those simple functions when you program the column.

Chapter 5: Designing Views 129


To use values from a Categories field, choose the Categories field as the
value for the column.

Setting up a Categories field


To produce a categorized column based on a Categories field, add a text or
keywords field to the form and name it Categories. The values for the
field can come from a predefined list, from users, or from lookup formulas.
To categorize documents created with the form, choose Actions -
Categorize.

Setting up categories in advance


To define a list in advance, create a computed keywords field and enter the
category names as its values.
Converting keyword synonyms to full category names
If you base a categorized column on a keywords field that contains
synonyms for the keywords, those synonyms are used as the category
names.
For example, a RequestType field that contains the following keywords
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 keywords field that uses synonyms, use a
hidden field or column formula that converts the synonyms back to their
full names:
@If(RequestType=HW;Hardware Request;RequestType=SW;
Software Request;Service Request);

Letting users create categories in the Categorize dialog box


To allow users to enter their own categories in the Actions - Categorize
dialog box, include an editable, multi-value, keywords field called
Categories on the form and select the field option Allow values not in
list.

Generating dynamic lists of categories


Use a keywords field named Categories, use @DbColumn formula to
calculate values for the field.

130 Application Developers Guide


Examples
Displaying the names of months
This formula is useful for a categorizing column that displays 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
keywords field with the following entries:
Bedroom
Kitchen
Living Room
To add subcategories, rewrite the keywords 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

Chapter 5: Designing Views 131


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.

About creating an All by Category view


To allow users to 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 Keywords field
Select Allow multi-values
Format: If you selected Keywords, leave the keywords list blank and
select Allow values not in list
A view named All by Category
A Categories column, placed as the leftmost column in the All by
Category view:
Width: 1 character
Column title: Leave the column title blank
Formula: Categories;
Sort the column by selecting Sort: Ascending and Type:
Categorized

132 Application Developers Guide


About 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:


Response forms are available to users 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 Basics 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 5: Designing Views 133


About 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))

134 Application Developers Guide


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)

About formatting date and time columns


To format values that result in a time or date displaying in a column select a
style in the Calendar tab of the Column Properties box.

Option name Selections


Show 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
Time zone Adjust time to local zone
Always show time zone
Show only if zone not local

Details
Show
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.

Date format
If you have an international date format set in your operating system, these
choices change, for example to suit the national conventions, for example,
from month/day to day/month.

Time format
If you have an international time format set in your operating system, these
choices change, for example, from 02:30 to 14:30.

Chapter 5: Designing Views 135


Time zone
You have three choices for time zone displays.
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 creators 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.

About formatting numbers columns


To format values that result in a number displaying in the column, select a
style in the Number 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.

136 Application Developers Guide


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.

About 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
document, Notes displays the documents percentage as it relates to the
category total. For each category, Notes displays the categorys percentage
as it relates to the overall view total.

Chapter 5: Designing Views 137


Details
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.

About 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.

Opening to a particular row in the view


To highlight a particular row when a user opens the view, select one of the
following On Open options in the Options tab of the View Properties box:
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.

138 Application Developers Guide


About formulas that look for values in columns and views
Lookup formulas are useful in keyword 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

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, 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

Chapter 5: Designing Views 139


@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.

About 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.

About the 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 design mode and select Default design for new folders and
views on the Options tab of the View Properties box.

About hiding a view


The 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. The view still appears in
the folders pane when users choose View - Show - Folders.

140 Application Developers Guide


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).

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
design toolbox, click the view name in the right 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 view doesnt appear to
anyone using Notes Release 4.0 or higher.

About 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.

Chapter 5: Designing Views 141


Choosing a style for unread marks
These options are set as a design property for a view. Open the Advanced
tab (the hat icon) 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.
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 S icon (the Style tab) 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.

142 Application Developers Guide


About 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 can occur manually when users press F9, as part of a
condition built into the view design, or as part of the Updall 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 (the hat icon) 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.
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 (View Properties - Options tab) 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.

Chapter 5: Designing Views 143


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 (the hat icon) 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 settings override 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
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 server task, which runs by default on each server at 2 A.M.,
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

144 Application Developers Guide


After each use and the view is used at 10 A.M. Tuesday, the index is not
actually discarded until 2 A.M. 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 A.M. Tuesday, it is only 16 hours old at 2 A.M. Wednesday when
Updall runs, so it is not deleted until the next time Updall runs at 2 A.M.
Thursday.
For more information, see the Maintaining the Domino System.

About limits for view elements


The full name of a view, including all synonyms and the cascading name,
can be up to approximately 64 characters.
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.)
A view can be 22.75 inches wide, The view can have a single column, or as
many columns as you can fit within 22.75 inches.
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.

Chapter 5: Designing Views 145


Chapter 6
Designing Navigators

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

About navigators
A database navigator is like a roadmap that directs users to particular parts
of an application. The basic Notes navigator presents a graphical display of
folders, views, and design elements, but you can create a custom navigator
that uses graphics, formulas, or scripts to best present your application.
Most navigators include hotspots that is, programmed areas that a
user clicks to execute an action. A hotspot can be text, graphics, or a
combination.
For example, Notes Help has a navigator to help users find specific topics
quickly. When users open Help, the introductory screen shows graphic
buttons. Clicking a graphic button leads to a particular view in the Help
database.
In most applications, you want the navigator to display automatically when
the application opens.
If your navigator inherits its design from a master template, do not make
any changes to the design of your navigator, since any changes you make
will be over-written by the master template.

Navigator objects
You create a navigator by combining objects. These might include a
background graphic for display only, and some combination of graphic
buttons and text objects. To create navigator objects, import or paste objects
from another application, or use the drawing tools Notes supplies. The
drawing tools include hotspot tools that you use to define a clickable area in
a navigator.

147
Navigator actions
A navigator action determines what happens when users click an object.
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
navigators:
Open another navigator
Open a view
Serve as an alias for a folder
Clicking the object displays the contents of the designated folder in the
view pane; dragging and dropping a document in the folder object adds
the document to the actual folder.
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 Programmers Guide.

Navigators in Web applications


To use a navigator in a Web application, you must turn on a setting in the
Navigator Properties box to make the navigator Web browser compatible.
When this setting is turned on, Designer creates an image map of the
navigator for Domino to present on the Web.
The only navigator object that is not supported in Web applications is the
polyline drawn object.

148 Application Developers 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. Select the database and choose Create - Design - Navigator.
2. Choose Design - Navigator Properties.
3. Give the navigator a name that describes its use.
4. To use the navigator in a Web application, check Web browser
compatible.
5. (Optional) Choose an initial view or folder to open along with the
navigator.
6. (Optional) Select Auto adjust panes at runtime so that users wont
have to manually resize a navigator that doesnt fit a window.
7. Click the navigator window.
8. Use the Create menu to draw objects or paste objects from the
clipboard.
9. Click each object and choose Design - Object Properties to assign a
name and style.
10. In the design pane, click a Run option and assign actions to each object.
11. Close and save the navigator.

Editing a navigator
To edit an existing navigator, open the navigator in design mode. Choose
Design - Navigator Properties and make changes as needed.

Details
Run options specify what happens when users click the object.
Click Simple action to choose a predefined automation, such as Open a
View.
Click Formula to define an action using the formula language.
Click Script to define an action using LotusScript.
For more information on adding an action, formula, or script to a navigator,
see Automating a navigator later in this chapter.

Chapter 6: Designing Navigators 149


About 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 them into a navigator as
a graphic background for the whole navigator or a graphic button that you
automate with an action. A navigator can have only one background
graphic, but it can have many graphic buttons.
Designer includes a set of drawing tools, available on the SmartIcons bar,
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 design mode.
The polyline drawing tool is not supported for use in Web applications.

Adding and enhancing graphics in a navigator


To paste a graphic from another product
1. Copy the graphic to the clipboard.
2. Select the database and choose View - Design.
3. In the navigation pane, click Design - Navigators.
4. Double-click the navigator.
5. Move the cursor where you want to place the graphic.
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.
7. Use drawing tools available from the Create menu or the SmartIcons
bar to create new objects or enhance existing ones.
8. Double-click a drawn object to edit its properties.
To import a graphic
1. Create a new navigator, or open an existing navigator in design mode.
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.
5. Use drawing tools available from the Create menu or the SmartIcons
bar to create new objects or enhance existing ones.
6. Double-click a drawn object to edit its properties.

150 Application Developers Guide


Details
The following types of files can be pasted or imported into a navigator:
Windows and OS/2
Bitmap
GIF
JPEG
PCX
TIFF 5.0s
To remove a graphic, choose Design - Remove Graphic Background.
Tips for drawing new objects
To create several identical 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 freeze an object at its current position and size, click the object,
choose Design - Object Properties, and select Lock size and position.
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.
To delete an object, select the object and choose Edit - Clear.

Adding text to and highlighting a navigator object


You can add text to all objects except polylines, hotspot rectangles and
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 clicked by the cursor.
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - Navigators.
3. Double-click the navigator.
4. Click the object.
5. Choose Design - Object Properties.
6. To add text to the object, enter text into the Caption box.

Chapter 6: Designing Navigators 151


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.
8. (Optional) Change the highlight border width, highlight border color,
and highlight background color.
9. (Optional) Click the Presentation 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.
For information on previewing using a Web browser, see Chapter 10.

Adding hotspots to navigators


A hotspot is a transparent object that defines a clickable area on a navigator.
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 design mode.
2. Select a hotspot tool from the SmartIcons palette. Hotspot tools are
red.
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 polyline hotspot.
4. Double-click the hotspot to edit its properties.

152 Application Developers Guide


About automating navigators
After you add objects to a navigator, automate it by attaching actions to the
objects. For example, to program a graphic button so that it opens a
particular view when a user clicks it, attach Action Open a View and
specify the view name.

Simple actions for navigators


Action: Open a view
When users click an object that opens a view or folder, the preview pane (if
it is open) changes to display the current document in the new view or
folder.

Action: Alias a folder


When users click an object that simulates a folder, the current folder (if one
is open) is replaced by the folder activated by the navigator; they can use
View - Go To to return to the original folder.

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.

Automating a navigator
To attach an action
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - Navigators.
3. Double-click the navigator.

Chapter 6: Designing Navigators 153


4. Select the object.
5. In the design pane, click Run: Simple action(s).
6. Select the simple action to run and supply any required information.
7. Close and save the navigator.
To attach a formula or script
1. Open the navigator in design mode.
2. Select the object.
3. To add a formula, click Run: Formula in the design pane.
4. Type the formula and click the green check mark to confirm it.
5. To add a script, click Run: Script in the design 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 Chapter 1 of the Programmers Guide.

Examples
Opening a view
A navigator that switches to another view gives users a graphical way to
choose a view so they dont have 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.
Making a navigator object that opens a navigator
A navigator 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. Users click a bar that
represents an areas sales to find out more information. Each bar in the first
navigator is a hotspot rectangle whose Switch to another navigator action
specifies the Weekly Details by Country navigator.

154 Application Developers Guide


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 in (for example, View by
country\France). Each bar in the second navigator is a hotspot rectangle
whose Switch to another view 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)

Chapter 6: Designing Navigators 155


Making a navigator object that runs a LotusScript program
When users double-click the object, 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

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 the 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.

Details
Open designated navigator in its own window 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.

156 Application Developers Guide


About 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.

Testing a navigator
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - Navigators.
3. Double-click the navigator.
4. Choose Design - Preview in Notes or Design - Preview in Web Browser.
5. Highlight and click each object to see if the highlighting and actions are
as you expected.
Clicking an object while previewing in Notes describes the
programmed action but does not perform it.
Clicking an object while previewing for a browser loads the browser
specified in the current location document and performs the action.
6. If the test produces unexpected results, choose Design - Preview in
Notes or Design - Preview in Web Browser to return to design mode.
7. Correct the problems and run the test again.
8. When the test shows no problems, close and save the navigator.
For information on previewing using a Web browser, see Chapter 10.

Chapter 6: Designing Navigators 157


Chapter 7
Adding Automation to Applications

This chapter explains how to add automation features to an application to


make it easier to use or to perform background processing.

About adding automation to an application


Automation in an application speeds up repetitive tasks, handles workflow,
updates information, performs calculations, runs programs, and checks for
errors. Automation features fall into two general categories: user-activated
automation and event-driven automation.
User-activated automation gives users shortcuts for complex or frequent
tasks or provides Web users with Notes menu equivalents. Examples
include a button that composes a new document or an Actions menu choice
that archives documents on demand.
Event-driven automation performs tasks at a predictable time for
example, when the task is scheduled to run, when users create new
documents, when a database opens. Event-driven automation is used for
error checking, mailing, updating, or starting another program, and so on,
or for doing work that users shouldnt have to activate manually. Examples
include a script that verifies if field values are valid when a user saves a
document and a scheduled program that sends reminders of overdue action
items to a project manager.
Automation features can be built into a database at many levels. The
following table lists which automation features apply at each level.

159
Automation features
Context User-activated automation Event-driven automation
Database Agents Agents
Database events
View Agents Agents
View actions View events
Document Agents Agents
Form actions Form events
Document buttons Field events
Document hotspots Action events
Button events
Hotspot events
Agent events

About actions, buttons, and hotspots


Create view actions, form actions, buttons, and hotspots to provide
one-click shortcuts for routine tasks and substitutes for menu choices. View
actions might allow users to compose, print, delete, or categorize
documents. Form actions, buttons, and hotspots might 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.
Form actions are part of a forms design, but unlike fields, buttons, and
hotspots, they arent stored with each document. View actions are part of a
views design. Use form or view actions instead of agents to present a
shortcut as a clickable button, to limit the scope of the automation, or to
show or hide actions under certain conditions. Use form actions instead of
buttons or hotspots when users need to see all the available choices in a row
at the top of a document, when actions arent tied to a particular section of
a form, or if formulas are complex and you dont want to save the formula
with each document.

160 Application Developers Guide


Buttons (shown in the first figure) and hotspots (shown in the second
figure) display in the body of a document created with a particular form.

Chapter 7: Adding Automation to Applications 161


About built-in form and view actions
New views and forms contain built-in actions. When a view or form is in
design mode and you choose View - Action Pane, you see these view and
form actions flagged with an asterisk.

Double-click the name of a built-in action to see or change its properties.


You cant change the programming attached to these actions, but you can
customize their appearance. By default, they are visible in the Actions menu
only.

162 Application Developers Guide


About the action bar
The action bar is a horizontal button bar that lies below the SmartIcons bar.
Each form and view has its own action bar that displays the actions that
were designed to display in the action bar.
Users see the view action bar when they open a view that has view actions
that were designed to display in the action bar.

Users see the form action bar when they open a document created with a
form that has form actions that were designed to display in the action bar.

Chapter 7: Adding Automation to Applications 163


Styling the action bar
To change the color and style for an action bar, click the Action Pane and
choose Design - Action Bar Properties when a form or view action is in
design mode. The style applies only to the action bar for the form or view
youre designing.
The default action bar background is gray.
To show a line under the action bar, choose any divider line option except
None:
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.
Change the line color and line style if you have a divider line and you want
something other than a single black line.
(Windows) Select Use system color if customized to use a system color
instead of the color chosen.

About the Actions menu


The Actions menu is a context-sensitive list of any automation 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.

164 Application Developers Guide


To make form and view actions available as choices in the Actions menu,
set the property Include action in Action menu. Actions appear listed
under user-activated agents in the menu. To make agents available as
choices in the Actions menu, set the option Manually From Actions
menu.

About naming actions and agents


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.

Chapter 7: Adding Automation to Applications 165


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

166 Application Developers Guide


About designing agents
Agents are stand-alone programs that perform a specific task in a database
for example, changing field values, sending mail messages, deleting
documents, interacting with external applications. Agents are the most
flexible type of automation because they can be run by users or in the
background and they arent tied to a specific view or form.
An agent requires:
Instructions about when to run (run manually by a user, run on a
schedule, and so on).
Instructions about which documents to process (all documents in the
database, changed documents, documents that meet search criteria).
A program that processes the selected documents.
To see the agents in a database, select the database and choose View -
Agents. Most templates come with some useful agents already built in.

From the agent view pane, you can run, test, and enable or disable agents.
Highlight an agent name and choose Actions - Run, Actions - Test, or
Actions - Enable. Double-click the name of an agent in the list to open it in
Design mode.

Chapter 7: Adding Automation to Applications 167


Table of agent run options
The run and document options for an agent define the agents run time and
general document collection.
Run options Document options*
Manually From Actions Menu All documents in database.
All new and modified documents since
last run.
All unread documents in view.
All documents in view.
Selected documents.
Run once.
Manually From Agent list All documents in database.
All new and modified documents since
last run.
All unread documents in view.
All documents in view.
Selected documents.
Run once.
continued

168 Application Developers Guide


Run options Document options*
If New Mail Has Arrived Newly received mail documents.
If Documents Have Been Created or Newly modified documents.
Modified
If Documents Have Been Pasted Pasted documents.
On Schedule Hourly, Daily, Weekly, All documents in database.
Monthly All new and modified documents since
last run.

* To narrow down the document collection, specify search conditions. Click


Add Search when the agent is in design mode.

Details
Manually From Actions Menu
Choose this for all user-activated agents or those triggered by
WebQuerySave or WebQueryOpen agents or formulas. It is the only choice
that allows users to see the agent in the Actions menu.
Manually From Agent List
Use for hiding agents that are run by another agent or that are that are still
being developed.
If the agent is called by another agent (the main agent), the document
selection is ignored. The main agent always determines the document
selection.
If New Mail Has Arrived
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
Use for workflow tasks where an action is performed based on new or
changed documents.

Chapter 7: Adding Automation to Applications 169


If Documents Have Been Pasted
Use if documents are pasted into the database routinely and you want to
modify them as they are being pasted.
Paste-activated agents cannot use @Command or @PostedCommand.
On Schedule Hourly/Daily/Weekly/Monthly/Never
Use to schedule agents to run at regular intervals. A scheduled agent that
uses @DbColumn or @DbLookup formulas can only access a database
stored on the same workstation or server.
Hourly
Use an hourly agent interval for high-priority databases, such as those
critical to a business process. An hourly agent is also useful for databases
that replicate several times a day, such as workflow applications that route
documents for approval.
Daily
Use a daily agent 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.
Weekly
Use a weekly agent for routine tasks. Examples include generating
summary reports and sending reminders.
Monthly
Use a monthly agent for low-priority maintenance tasks. Examples include
archiving documents and distributing company newsletters.
Never
On Schedule Never is reserved for Release 3 background macros that have
the Never schedule selected. To run such a macro, select one of the other
schedule options listed above.

170 Application Developers Guide


Table of agent search options
The following table lists the document search options available for agents.
To access these options, click Add Search when an agent is in Design mode.
Search Selection 1 Selection 2
By Author contains <author name> or choose from
does not contain Address Book
By Date date created is on
date modified 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
By Field <field name> contains
does not contain
<date field name> 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
<number field name> is equal to
is greater than
is less than
is not equal to
is between
is not between
By Form <form name> <field values> for multiple fields
By Form Used <form name>
In Folder <folder or view name>
Words and Any of the words below Up to eight entries
Phrases All of the words below

Chapter 7: Adding Automation to Applications 171


About choosing which server runs a scheduled agent
To prevent replication conflicts caused by agents that change documents
running on multiple servers, designate which server runs a scheduled
agent. Set up replication to distribute changes to databases on other servers.
To choose a server, click Schedule while an agent is in design mode and
specify a server in the Run only on list or select Choose when agent is
enabled.

Running the agent on the original server


To run the agent on the same server where you create the agent, leave the
default setting in the Run only on box.

Running the agent on another server


To run the agent on another server, select a server in the Run only on list
box or enter a server name.

Running the agent from any server


If you cant specify a server in advance, enter * (asterisk) as the server name
in the Run only on box. This wildcard entry allows any server to run the
agent. Choosing this may result in replication conflicts if several servers run
the same agent and change documents.

Allowing users to choose which server runs the agent


If you select Choose when agent is enabled, users are prompted to select
a server when they enable the agent. This is useful for distributing agents in
ready-to-use applications. Many Designer templates ship with this option
selected.

About running restricted LotusScript agents


The Agent Manager section of the Server document in the Public Address
Book determines whether you can run restricted and/or unrestricted
agents. Users or groups allowed to run unrestricted agents have full access
to the servers system and can manipulate system time, file I/O, and
operating system commands. Users or groups allowed to run restricted
agents have access to a subset of LotusScript commands which allows
limited access to the servers system.

172 Application Developers Guide


The following table shows the limitations of using restricted agents.
Task Restricted LotusScript class, method, or statement
Opening network databases Notes database Open method
Notes database OpenIfModified method
Notes database OpenMail method
NotesLog OpenNotesLog method
Opening local databases Databases are opened using the agent owners
user ID. Therefore, actions performed on the
database are constrained by the users access
privileges.
Creating or deleting Notes database New method
databases Notes database Create method
Notes database CreateFromTemplate method
Notes database CreateReplica method
Notes database CreateCopy method
Notes database Remove method
Kill filename statement
Name oldname as newname statement
Filecopy source, destination statement
Using Environment variables Notes session SetEnvironmentVar method
Notes session GetEnvironmentVar method
Notes session GetEnvironmentString method
Using a disk-based log file NotesLog OpenFileLog method
Write #filenum, expr statement
Print #filenum, expr statement
Put filenum, pos, var statement
Encrypting or signing Notes document Sign Method
Notes document Encrypt Method
Notes document SignOnSend Method
continued

Chapter 7: Adding Automation to Applications 173


Task Restricted LotusScript class, method, or statement
File I/O 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
Setting system date/time Date and Date$ statements
Time and Time$ statements
Calling a C routine External C calls Declare statement
Executing another ActivateApp statement
application Shell statement
Making OLE calls Rich text item EmbedObject method
Rich text item GetEmbeddedObject method
GetObject(path) statement
CreateObject(classname) statement
Restricted if cant get object:
Activate(hide) method
ExtractFile(path) method
DoVerb(name) method
Remove method

174 Application Developers Guide


About agents and the access control list
The following options in the database access control list affect agents.
To create a shared agent, a user must have Designer access or higher.
To create a personal non-LotusScript agent that is stored in a shared
database, a user must be assigned the Create personal agents option.
To create a shared LotusScript or Java agent, a user must be assigned
the Create LotusScript agents option in the access control list. To
store the agent in a shared database, a user must also be assigned the
Create personal agents option.

About events
When users open a database and work with documents, Notes identifies the
events for example, opening a database, opening a view, opening a
document that occur as users proceed through the database. To
automate a piece of work, check for errors, prohibit certain actions, or
prompt for user input, you can attach programming to these events.
Examples include displaying an error message if a user closes a document
without filling in a required field, recalculating fields when a user saves a
document, preventing users from pasting documents, or displaying a
prompt when a user clicks a button. Choose programmed events rather
than agents when the timing of the program must be precise or the program
is tied to a particular design element.

Seeing the programming attached to events


Every design element has pre-assigned events that you can program. When
you open a design element in design mode, browse through the Event list
box in the design pane. An event that has an attached program shows a
script or formula in the editing window below. Most Designer templates
have some programmed events.
Tip To scroll through event scripts for a design element, click the design
pane, and use CTRL+PGUP and CTRL+PGDN to scroll through event code.
Youll see declarations first, then the scripts attached to events.

Chapter 7: Adding Automation to Applications 175


Table of events
The following table lists events that can be automated. Most can be
automated with a script or formula; a few can be automated only with one
or the other.
Location Name Timing
Database Initialize When a database is being loaded
Postopen After a database is opened
Querydocumentdelete Before a document is marked for
deletion
Postdocumentdelete After a document is deleted (the
document is still available for
additional processing)
Querydocumentundelete Before a document is unmarked for
deletion
Queryclose When a database is being closed
Terminate When a database is being closed
continued

176 Application Developers Guide


Location Name Timing
All Initialize When a view or folder is loaded
Views/Folders during database open
Queryopen Before a view is opened during
database open
Postopen After a new view is opened
Queryopendocument Before a document is loaded
Queryrecalc Before a view is refreshed
Queryaddtofolder Before a document is added to a folder
Querypaste Before a document is pasted
Postpaste After a paste operation
Queryclose When a view is being closed
Terminate When a view or folder is being closed
Calendar views Regiondoubleclick When a region in a calendar view is
(in addition to double-clicked
events that apply
to all views)
Querydragdrop Before a drag-and-drop operation in a
calendar view
Postdragdrop After a drag-and-drop operation in a
calendar view
Form/Subform Initialize When a document is being loaded
Queryopen Before a document is opened
Postopen After a document is opened
Postrecalc After a document is refreshed (and
values are recalculated)
Querysave Before a document is saved
Querymodechange Before a document is changed to read
or edit mode
Postmodechange After the user changes the document
to read or edit mode
Queryclose Before a document is closed
Terminate Occurs after the document is closed
continued

Chapter 7: Adding Automation to Applications 177


Location Name Timing
WebQueryOpen Runs an agent before a Web document
displays. The formula must use the
following syntax:
@Command([ToolsRunMacro];agentn
ame).
WebQuerySave Runs an agent before a Web document
is saved. The formula must use the
following syntax:
@Command([ToolsRunMacro];agentn
ame).
Field Initialize When a document is being loaded.
Occurs after the Form Initialize event
Entering When a document is in edit mode and
the user clicks or tabs to an editable
field
Exiting When the user clicks or tabs to another
field.
Terminate When the document is being closed
Action, button, Initialize When the object is being loaded
hotspot
Objectexecute When the object is activated by an
OLE2 server that is FX/NotesFlow
enabled
Click When an object is selected
Terminate When an object is being closed
Agent Initialize When an agent is being loaded
Terminate When an agent is being closed

About programming database events


Database events pinpoint database-wide activities such as opening and
closing a database and deleting and undeleting documents. Ideas for
programmed database events include:
Programming the PostOpen event to open a specific view for
example, to direct users to a view that contains action items.
Programming the QueryDocumentDelete event to prevent users from
deleting a particular document for example, if the value of a status
field on an action item is Open.

178 Application Developers Guide


Programming the PostDocumentDelete event to archive a deleted
document.
Programming the QueryClose event to prevent users from closing a
database for example, if there are still action items in the action item
view assigned to them.

About programming view and folder events


View events occur when users work in a specific view or folder and include
opening or closing a view, adding documents to a calendar view, or adding
documents to a folder.

Programmed view events


Ideas for programmed view events include:
Programming the QueryOpen event to prevent users from opening a
view in certain circumstances for example, preventing users from
opening a month end view before the twentieth day of the month.
Programming the PostOpen event to create a new document or open an
existing one.
Programming the QueryRecalc event to inform users before a large
view refreshes that it could take a while and ask them if they really
want to proceed.
Programming the QueryPaste event to prevent users from pasting
documents into the database.
Programming the PostPaste event to change the value of StartDateTime
and EndDateTime in the document when you paste an appointment on
a particular day and time slot. The mail template uses this calculation
for both the PostDragDrop and PostPaste event.
Programming the QueryClose event to prevent users from closing a
view for example, if there are still action items in the action item
view assigned to them.

Programmed calendar view events


In addition to the events available for all views, calendar views have
specific events. Ideas for programmed calendar view events include:
Programming the RegionDoubleClick event to create a new document
when users click an area in a calendar view. (The mail template uses
this technique.)
Programming the QueryDragDrop event to 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.

Chapter 7: Adding Automation to Applications 179


Programming the PostDragDrop event to change the value of
StartDateTime and EndDateTime in the document after you drop an
appointment on a particular day and time slot. The mail template uses
this calculation for both the PostDragDrop and PostPaste event.

Programmed folder events


In addition to the events available for all views, folders also have the
QueryAddToFolder event.
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.

About programming form events


Form events occur at the document level for example, 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.
Ideas for programming form events include:
Programming the Initialize event to load an additional program before
a document displays.
Programming the QueryClose event to check for errors and validate
fields before closing a document.
Programming the QuerySave event to 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).
Programming the QuerySave event to 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.

180 Application Developers Guide


About programming field events
Field events capture users movements into or away from a field. Ideas for
programming field events include:
Programming an Entering event to refresh hide-when formulas.
Programming an Exiting event to guide users to a certain field.
Programming an Exiting event to verify that users supplied valid
information.

About programming action, button, and hotspot events


The Click event occurs when users click actions, buttons, or hotspots, or
choose events 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 include:
Programming a click event to compose a new document.
Programming a click event to save a form.
Programming a click event to make a calculation.

About programming agent events


When you write a script for an agent, always add the programming to the
Initialize event. The Initialize events stores all the programming associated
with the agent.

About hiding actions, buttons, and hotspots


If an action, button, or hotspot is not relevant to all users or situations, use
the Hide tab of the Properties box to specify when to hide the object.

Hide action from Notes R4.6 or later


Hides an object when it is viewed from a Notes workstation. This is useful
for action bar buttons that you provide to Web users as substitutes for
Notes menu choices.

Hide action from Web Browsers


Hides an object when it is viewed from a Web browser. This is useful for
hiding buttons that arent relevant to Web users.

Chapter 7: Adding Automation to Applications 181


Hide when opened for reading; Hide when previewed for reading
Hides the object when a document is opened in read mode from the
preview pane or as an open document. These are useful for actions 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 the object when a document is opened in edit mode from the preview
pane or as an open document. These are useful for actions 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


(For buttons and hotspots) Hides the object when users print a document.
This is useful for removing clutter from a printed document.

Hide when copied to the clipboard


(For buttons and hotspots) Hides the object when users copy a document.
This is useful for removing clutter from a copied document.

Hide if formula is true


Hides the object under certain conditions for example, based on user
name or access level in the access control list. For example, the following
formula hides the action from all users except Barbara Meehan:
@If(@Name([CN];@UserName) !=Barbara Meehan;@True;@False)

182 Application Developers Guide


About programming the automation
The design pane offers several choices for adding programming to form
and view actions, buttons, hotspots, agents, and events. Click the button for
the type of programming you want to add and then build the program in
the editing window.

Simple actions
Using the simple actions supplied with Designer, you can add automation
to elements without knowing a programming language. In the design pane,
click Simple action(s), then click Add Action and choose an action from
Action list. To delete a simple action, click it in the formula window, and
choose Edit - Clear. 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.
To write a stand-alone formula, click Formula in the design pane and
write the formula in the window below.
To combine a formula with a simple action, click Simple action(s) and
then click Add Action. Choose @function formula from the Action list
and write the formula in the editing window.
Click Fields & Functions to select an @function or field and paste it into
your formula. Click @Commands to select and paste an @command into
your formula.

Chapter 7: Adding Automation to Applications 183


Agents run the complete formula on a document before proceeding to the
next document.
Using @Command formulas with actions, buttons, 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 button can operate on a field or an entire document, but
not on 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,
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.

LotusScript
To write a LotusScript program, click Script and write the program in the
editing window.

Java
To attach a Java program to an agent, write the program in a Java
development environment, and then click Java and click Import Class
Files to import the files into the agent.

Table of simple actions for automation features


Use the following simple actions with view actions, form actions, buttons,
and hotspots. Web applications do not support simple actions.
Function name Description Additional steps
Copy to Database Copies the selected Click Choose Database. Select
document to the database the server and target database
you specify. in which to paste the
documents and click Select.
Copy to Folder Copies the selected Select the folder(s) to which
document to the folder you selected documents should be
specify. copied. (Folder(s) must exist
already).
continued

184 Application Developers Guide


Function name Description Additional steps
Delete from Database Deletes the selected
documents from the
database.
Mark Document Read Marks selected documents
as read.
Mark Document Marks selected documents
Unread as unread.
Modify Field Replaces or appends a Select the field to be modified
single field value with a and type a new value. Click
new text value you specify. Replace value or Append
value.
Modify Fields by Form Replaces several field Select the form that contains
values on a form with new the fields you want to replace.
text values you specify.
Move to Folder Moves the highlighted Select the folder(s) to which
document in a view or selected documents should be
folder to a different folder. moved. (Folder(s) must exist
already).
Remove from Folder Removes selected Select the folder(s) from which
documents from a folder selected documents should be
you specify but does not taken.
delete the documents from
the database.
Reply to Sender Sends a reply to a mail Click Reply to sender only
memo automatically. or Reply to all.
In the Body field, add the
reply text.
(Optional) Click Include
copy of document to append
the original message to your
reply.
Select Reply only once per
person if a person is included
in multiple mailing groups.
continued

Chapter 7: Adding Automation to Applications 185


Function name Description Additional steps
Run Agent Allows you to chain agents
together with other agents
or combine LotusScript
programs and @function
formulas in one agent. The
agent to be run must
already exist in the
database.
Send Document Mails the current document
to the recipients designated
in the documents SendTo
field.
Send Mail Message Mails the selected Add the recipients in the To:
document as a whole field and a one-line
document or as a link. description in the Subject
field.
Add descriptive text in the
Body field.
Select either Include copy of
document or Include link to
document.
Send Newsletter Searches a database for Add the recipients in the To:
Summary documents matching field and a one-line
conditions you specify, description in the Subject:
then sends a summary field.
document with links to the Write descriptive text in the
individual documents. Body field.
Leave Include summary for
each document using view
selected, and choose another
view from which information
should be copied.
@Function Formula Adds a customized
@function formula to
simple actions.

Details
Copy to Database
You can copy and paste selected documents in the same database or
another database. They are marked as read in the destination database.
Copy to Folder
Using an action to copy 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.

186 Application Developers Guide


Delete From 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.
Mark Document Read
The Mark document read option is useful for marking an unread
document as read without having to open 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.
This action is useful when combined with an action that changes field
values. Then when users change the values in a document, they can mark it
read at the same time.
Mark Document Unread
The Mark document unread option is useful for flagging a document that
users want to read again.
Modify Field
This action replaces only text values for documents in edit mode. To replace
a value with something other than text, create an action that uses an
@function formula or LotusScript program. The Modify Field action can
modify the value of a hidden field, as long as you can supply the correct
name of the field.
The Append Value option for Modify Field 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, the Append action is not available if a
database does not contain any documents. To include the append action in
a database that has no documents, such as a database template, do the
following: create a placeholder document containing the desired field,
create the agent, and then delete the document. Or, use a formula rather
than the simple action.
Modify Fields by Form
This action replaces only text values. To replace a value with something
other than text, create an action that uses an @function formula or
LotusScript program. This action marks processed documents as read.
The Modify fields by form action allows you to replace field values even
if you dont know the internal Notes names for fields.
Move to Folder
Using an action to move a document from one folder to another removes
the document from the source folder. The document is not deleted from the
database and remains in any views that select it.

Chapter 7: Adding Automation to Applications 187


Remove from Folder
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.
Run agent
The collection of documents that an agent runs on is determined by the first
agent run. All subsequent agents use the same collection, 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.
Send Document
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 Newsletter Summary
Send Newsletter contains view-like summary information about the
document. For example, if the view displays Date, Author, and Title
columns, the one-line summary adds that information next to the document
link.
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.

188 Application Developers Guide


Mailing options for all Send and Reply actions
If you create a Send or Reply action, the More option allows you to create
detailed addresses by typing entries or writing formulas for the To:, cc:,
bcc:, and Subject: fields.
To type an entry, click Text and type the entry.
To use a formula, click Formula and type the formula.
The Body field accepts only plain text. It does not accept styled text,
graphics, or attachments.

About attaching Java programs to an agent


Agents run on Domino servers can run Java programs, but you must create
the class files in advance. Domino supports programs written in Java 1.1.x.
To access Notes databases, use the Java Notes classes.
Files for agents can be of the following types:
Class *.class
Archive *.jar
A Java program is generally not one file but a whole collection of files. You
must designate one as the Base Class, which is the starting point for the
agent program. There can also be archive files and source files, stored either
on your local workstation or on a server.
When you write a Java agent, the class you write must extend the class
lotus.notes.AgentBase. The code you want to execute when the agent runs
is in the NotesMain() method. The Java Programmers Guide describes the
Java Notes classes and is available as a database (javapg.nsf) and installs
with other documentation databases in the DOC subdirectory.

Attaching Java programs to an agent


1. With the agent in Design mode, click Java in the design pane.
2. Click Import Class Files.
3. Select the base directory. Files must be in the base directory or in a
subdirectory of the base directory.
4. Select the files you need and click Add or Add All.

Chapter 7: Adding Automation to Applications 189


5. Select each file in the Selected Files list and use the up and down arrows
to designate the order in which Domino should load them at run time.
6. Click OK.
7. If you want a Base class that is not the first in the files list, type the
name in the Base Class list.
To attach new or changed files later, click Reimport Class Files.
To change the order of selected files later or to delete files, click Reorganize
Class Files.

About Java Notes classes


Java Notes classes parallel the LotusScript Notes back-end classes. You can
use these classes from any Java program within the Notes Designer
environment or outside of it as long as Notes Release 4.6 is installed on
the machine.
The Java Programmers Guide is available as a database (javapg.nsf) and
installs with other documentation databases in the DOC subdirectory.

Creating a form or view action


1. Open the form or view in Design mode.
2. Choose Create - Action.
3. Give the action a title.
4. Select a button icon.
5. Select the location and position for the action.
6. (Optional) Click the Hide tab to stipulate hide-when conditions.
7. (Optional) Choose Design - Action Bar Properties to change the style of
the action bar that is associated with all actions for this form or view.
8. Add the programming for the action.
9. Save the form or view.

Other form and view action procedures


To open an action in Design mode later, open the form or view, choose
View - Action Pane, and double-click the action name from the action pane
displayed on the right.
To copy an action, click the action name in the action pane and choose Edit -
Copy and Edit - Paste.
To delete an action, click the action name in the action pane and choose Edit
- Clear.

190 Application Developers Guide


Examples
Sending a document to reviewers
You want to simplify the process of distributing proposed Concert
Schedules to a review board. You add a form action and a SendTo field to
the Concert Schedule form so schedules can be mailed.
1. Create a SendTo field on the form that lists the members of the review
board.
2. Create a form action named Distribute for Review and assign it the
action Send Document.
3. Show the form action on the action bar and on the Actions menu and
assign an icon.
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.);
Composing new documents from the view
To make it easy for users to create new documents, you add a view action
named New Main Topic and display it in the action bar. The formula is:
@Command([Compose];Main Topic)

Enabling Web users to delete documents


To allow Web users to delete an open document, you must create a form
action (Web users dont have access to Notes menus). Create an action that
uses this formula, name the action Delete, and display it in the action bar:
@Command([EditClear])

Chapter 7: Adding Automation to Applications 191


Creating a button on a form
1. Open the form in Design mode or a document in edit mode.
2. Click where you want to place the button and choose Create - Hotspot -
Button.
3. Give the button a label.
4. (Optional) Click the Hide tab to stipulate hide-when conditions.
5. (Optional) Click the Type style tab to change the font or color of the
label.
6. Add the programming for the button.
7. Save the form.

Other button procedures


To change the properties for a button, click it and choose Button - Button
Properties.
To change the programming for a button, click it and choose Button - Edit
Button.
To delete a button, click it and choose Edit - Clear.

Examples
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)

192 Application Developers Guide


Creating a text or graphic hotspot
1. Open the form in Design mode or a document in edit mode.
2. Highlight the text or graphic that will be the hotspot.
3. Choose Create - Hotspot - Action Hotspot.
4. (Optional) Click the Hide tab to stipulate hide-when conditions.
5. Add the programming for the hotspot.
6. Save the form.

Other hotspot procedures


To change the properties for a hotspot, click it and choose Hotspot -
Hotspot Properties.
To change the programming for a hotspot, click it and choose Hotspot -
Edit Hotspot.
To delete a hotspot, click it and choose Hotspot - Remove Hotspot.

Examples
Using a hotspot graphic to give users additional information
You want to give users information about printing a Conference Room
Schedule document. You create a hotspot graphic (with a picture of a
printer) on the Schedule form and add the following formula. You choose
the hide option for the graphic so that it is hidden when the document is
printed.
@Prompt([OK]; Printing Tip; Click the Print button. Then
select Setup... and choose Landscape orientation. This
picture will not show on the printout.)

Creating an event script or formula


1. Open the design element to which you want to add automation, or for a
database event, click Other - Database Script from the design toolbox.
2. Select the event from the Event box.
3. Add the programming for the event.
4. Save the design component.
To delete a script or formula, highlight the code and press DEL.

Examples
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:

Chapter 7: Adding Automation to Applications 193


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

194 Application Developers Guide


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 persons last name.,
0, ERROR
End If
End Sub

Creating an agent
1. Select the database and choose Create - Agent.
2. Give the agent a name.
3. Click Shared agent.
4. Select an option for When should this agent run?
5. Select an option for Which document(s) should it act on?
6. (Optional) To refine the document selection, click Add Search and
specify additional selection conditions.
7. (Optional) Click Options to add a short description or to make search
results visible to users.
8. Add the programming for the agent, using the Initialize event.
9. Save the agent.

Other agent procedures


To open an agent in Design mode later, choose View - Agents and
double-click the agent you want to open.
To copy or delete an agent, choose View - Agents, click the agent name, and
choose Edit - Copy or Edit - Clear.

Chapter 7: Adding Automation to Applications 195


Details
Schedule options
When specifying A.M. and P.M., you must type the entries without periods:
A.M., P.M.
Hourly: Options are the hourly frequency, the starting and ending times,
the start and end dates, and weekends. The default is every hour, starting at
12 A.M. and ending at 12 A.M.
Daily: Options are the starting time, the start and end dates, and whether
the agent runs on weekends. The default is 1 A.M.
Weekly: Options are the day of the week and the starting time, and the start
and end dates. The default is Sunday at 2 A.M.
Monthly: Options are the day of the month, the starting time, and the start
and end dates. The default is on Day 1 at 2 A.M.
Never: On Schedule Never is reserved for Release 3 background macros
that have the Never schedule selected. To run such a macro, change the
selection to one of the regular schedule options.
Modifying, creating, or selecting documents with agents
For backwards-compatibility with Notes Release 3 agents, you can choose
what an agent that runs an @function formula does to its selected
documents. Change the setting in the lower-right corner of the design pane
or in the Add Action window when you select @Function formula as the
action. The options are worded slightly differently, depending upon
whether they are available from the design pane or the Add Action
window.
Modify documents and Update existing documents when run
Modifies and saves any documents that meet the selection criteria. This
is the default setting.
Create new documents and Create new document when run
Makes a copy of each document that would be changed, then modifies
and saves the copies, leaving the original documents untouched. This
setting is useful for keeping a history of changes to each document. It is
also useful during testing, although you must delete the original
documents later.
Select documents in view and Select document when run
Selects the documents and places a check mark in front of each
document that meets the selection criteria, but doesnt actually change
them. This setting is useful during the testing phase to make sure
document selection is correct. You can change to one of the other
options after testing.

196 Application Developers Guide


Examples
Sending announcements
You are designing a Corporate Announcements database where managers
want to send notices for important announcements. They decide on a
case-by-case basis which announcements are circulated by selecting them
from the view before running the agent.
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. Create a shared agent named Mail announcements.
2. Select the run option Manually From Agents List.
3. Select Selected documents.
4. Select Simple action(s) and click Add Action.
5. Select Send Newsletter Summary.
6. In the To box, type the group name from the Public Address Book: All
Personnel.
7. In the Subject box, type: Important Announcements.
8. In the Body box, type: Please note the following new announcements:
9. Select Include summary for each document in view, select the All By
Date view, and click OK.
Sending automatic replies from a mail-in database
For a mail-in Survey database that collects employee responses about the
company benefits package, you create an automatic response agent so
employees receive a confirmation that their response was received.
1. Create a shared agent named Send Thank-You.
2. Select the run option If New Mail Has Arrived.
3. Select Simple action(s) and click Add Action.
4. Select Reply to Sender and click Reply to sender only.
5. In the Body box, type:
Thank you for taking the time to respond to our survey. We will
distribute the results as soon as they are ready.
6. Click OK.

Chapter 7: Adding Automation to Applications 197


Testing an agent
Test agents during development and again before copying the agent to a
server database.

To test an agent during development


You can quickly test an agent by simulating a run without affecting
documents.
1. Select the database and choose View - Agents.
2. Select the agent and choose Actions - Test.
3. Read the Test Run Agent Log which describes how many documents
would be processed and what action would be taken if the agent were
actually run and click OK.

To test before copying an agent to a live 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.
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.
2. 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 Public
Address Book. Mail a few documents to the test database.
3. If the agent works on pasted documents, paste a few documents into
the database before running the test.
4. If you dont need to run the agent from a view, select the database and
choose View - Agents, select the agent youre testing, and choose
Actions - Run; otherwise, open the database, select the view, and
choose Actions - <Agent Name>.
5. Make changes to the agent to fix any problems that the test run shows.
If necessary create a new copy of the database to run the agent again.
6. When the test shows no problems, copy the tested agent to the live
database.

198 Application Developers Guide


Checking the Agent Log
Every time an agent runs, it writes a report that includes when it ran, how
many documents it ran on, and what action 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. Click OK to close the Log window.
If there is no Log (because the agent has never run), you see the message,
This agent has never been run before.

Disabling scheduled agents


If you have Designer access or above, you can disable any agents, except
manually run agents, to prevent servers from running them automatically.
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. Click the enabled agent and choose Actions - Enable.
The checkmark disappears next to the agent name.
To enable a disabled agent, click the agent and choose Actions - Enable.

To disable all automated agents in a database


Disabling all agents is useful for debugging a problem with an agent
running on a server.
1. Select the database and choose File - Database - Properties.
2. Click Disable background agents for this database.

Chapter 7: Adding Automation to Applications 199


About security features that affect automation formulas
Form actions and hotspots work only if users are in the correct context and
have enough access to perform the function. For example, a button whose
formula uses @SetField to change a field value does nothing if the
document is in read mode or if a user has only Reader access.
An action or hotspot cannot usually harm a server-based database because
most users lack the access to do any damage. However, since you implicitly
receive Manager access to all local databases unless they are encrypted
locally, a formula could potentially change documents in a local database. If
you are unfamiliar with an action, review its formula before running the
action.
If the users NOTES.INI file (or Notes Preferences file, for Macintosh users)
includes the 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.

200 Application Developers Guide


Chapter 8
Restricting Access to and Securing Parts of an
Application

This chapter describes Notes features for limiting access to parts of an


application. It does not provide a comprehensive description of Notes
security features. For more information on security, see the Database
Managers Guide.

About security in an application


Notes offers a multi-layered approach to security. You can secure a system
from the field level all the way up to the domain level. 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 features, such as the database design and agents.
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.
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 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.

201
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 Chapter 7. For information on
securing a database using the access control list, see the Database Managers
Guide.

About 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.

Giving designers access to a database


1. Select the database and choose File - Database - Access Control.
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.
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.

202 Application Developers Guide


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.

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 the Database Managers Guide.

About restricting access to documents


Notes 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 view or folder that restricts who can
update document in the view or folder.

Chapter 8: Restricting Access to and Securing Parts of an Application 203


Create a form access list to restrict access to all 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 only some users 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.

To create a read access list


1. Open the view or folder in Design mode.
2. Choose Design - View Properties or Design - Folder Properties.
3. Click the key icon (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 or
Public Address Book.
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 documents in 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.

Details
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.

204 Application Developers Guide


Examples: 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 Public Address Book for the
people he wants to include in the access list, Rajeev defines an access role
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 Public Address Book.

Restricting who can update documents in a folder


To allow only some users to update documents in 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.
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - Folders.
3. Double-click the view or folder.
4. Choose Design - Folder Properties.
5. Click the key icon (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 or
Public Address Book.
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, use access control
settings in the form properties. This 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 want to prevent

Chapter 8: Restricting Access to and Securing Parts of an Application 205


some users from having access to documents that contain sensitive financial
information. In addition, you might want to restrict actions users can take
with forms and the documents created from them. For example, you might
want to prevent users from printing, copying, or forwarding a company
phone list.
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 the next level of access control.
You can create form access lists that specify who can create, edit, print,
forward, or copy information. Limiting who can create a form also shortens
the Create menu by removing restricted forms from the menu.
Users who have Editor-or-above access who are not in the create access list
but are in the read access list for a form or document can still edit
documents.

Authorized readers
The following people can read a document that has restricted read access:
Users listed in the forms read access list
Users listed in the forms Readers field
Readers field names are added to a documents read access list.
Users listed in the author name field in the document

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 in Design mode.
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.
6. Deselect All readers and above in the Default read access for
documents created with this form section.

206 Application Developers Guide


7. Click each user, group, server, and access role you want to include.
8. (Optional) Disable printing, forwarding, and copying to the clipboard.
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 in Design mode.
2. Choose Design - Form Properties.
3. Click the Security tab (the key icon).
4. Click Disable printing/forwarding/copying to clipboard.
5. Close and save the form.

About 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 the form.
Entries in a Readers 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 read a document, even if you list them in a Readers
field. Users with Editor access or above cant read documents if they arent
included in a Readers field.
Any users who already have Editor (or higher) access to the database can
still edit the document if:
They are listed in the forms read access list, Readers field, or Authors
field.
The document has no read access list restrictions, no Readers field, and
no Authors field.

Chapter 8: Restricting Access to and Securing Parts of an Application 207


About using an Authors field to restrict who can edit specific documents
An Authors field works in conjunction with Author access in the database
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. To
expand the Author access by granting limited editing access, use an
Authors field. An Authors field allows you to restrict users to editing only
the documents that they create and that specifically list them in the Authors
field.
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.

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.
1. Open the form in Design mode.
2. Create a field, or click an existing field. Then choose Design - Field
Properties.
3. Select Readers or Authors as the field type.
4. Select Editable to allow authors and editors to modify the list; be sure
to include yourself in the default value formulas, so there is at least one
value.
5. Select Computed to write a formula that computes the reader or author
names.
6. To create editable or computed field values, click the design pane, select
a formula type, and write the formula; click the green check mark to
save the formula.
Note Include server names in the list if the database will replicate.

208 Application Developers Guide


7. Select a Choices option other than None to generate a list of readers or
authors from which users can select.
8. (Optional) On the Basics tab, select Allow multi-values to allow more
than one name to be stored in the field.
9. (Optional) On the Basics 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.
10. Close and save the form.

Details
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, users either press
CTRL+ENTER or, if chosen 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.
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. Notes fills in the first name that matches
the characters the user types.
Use Address dialog for choices
This option displays the Names dialog box so users can select names
from a Personal or Public Address Book. 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.
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 Notes database view. Select the database to look up, select a view,
and select a column number.

Chapter 8: Restricting Access to and Securing Parts of an Application 209


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 OConnor
Access role names are surrounded by quotation marks and square brackets.
[Scheduling Committee]
Viewing the contents of the $UpdatedBy field
If a document contains an Authors field, Notes 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.
Users can click and hold the Authors field in a document theyre reading to
display the contents of the $UpdatedBy field. Notes 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 what theyre seeing in the list.
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.

Examples
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.

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.

210 Application Developers Guide


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.

About tracking who edits a document


If a document contains an Authors field, Notes 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 . Notes 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.
Notes 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.

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 in Design mode.
2. Create a field, or click an existing field.
3. Click the Options tab.
4. Select Security options: Must have at least Editor access to use.
5. Close and save the form.

Chapter 8: Restricting Access to and Securing Parts of an Application 211


About creating forms, views, and agents for public access
A public access list, like Readers and Authors fields, works with the
database access control list to expand users access to specific views, forms,
and documents. Creating forms and views enabled for public access allows
you to provide users with No Access or Depositor access the ability to view
specific documents, forms, and folders without giving them Reader access
to the entire database. Users who have this access level in the database ACL
will see only documents, folders, and views that have been designated as
available for public access in the Form/Folder/View Properties box.
Creating agents enabled for public access allows users with No Access or
Depositor access the ability to view and use any manually-run agents.
To create public documents, create a form, create a $PublicAccess field in
the form, change the security for the form to allow public access, 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.
For more information on creating a public access list in the ACL, see the
Database Managers Guide.

Creating forms, views, and agents for public access


To create a form for public access
1. Choose Design - Form Properties.
2. Click the Security tab.
3. Select Available to Public Access Users.
4. Create a field.
5. In the Name field, enter $PublicAccess.
6. In the Type field, select Text and Computed when composed.
7. In the design 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.
8. To hide this field from users, select the Hide tab and Specify hide-when
conditions.
9. Save the form.

To create a view for public access


1. Open the view in Design mode.
2. Choose Design - View Properties.
3. Click the key icon (Security tab).

212 Application Developers Guide


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.
5. Save the view or folder.

To create an agent for Public Access


1. Open the agent in Design mode.
2. Click Options.
3. Select Available to Public Access Users.
4. Save the agent.

About encrypting documents


Encrypted documents contain one or more fields that are enabled for
encryption and that are linked to keys that encrypt the field data. 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 Public Address Book.
Public keys are used for encrypting mail documents.

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 Public
Address Book. 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.

Chapter 8: Restricting Access to and Securing Parts of an Application 213


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.

Making fields for 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.
1. (Optional) Create an encryption key to use secret encryption.
2. Enable encryption for a field.
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
For more information, see the Database Managers Guide.

Details
You have three choices for associating encryption keys with documents.
Encrypt all documents with the same encryption key
This is the most convenient for users, but doesnt give them the
flexibility of choosing an encryption key.
Create a field that generates a list of frequently used keys

214 Application Developers Guide


This requires users to fill in a field to determine which key to use. This
is a good choice if you expect some variation in the encryption keys
users want, and the list of possible keys is predictable.
Allow the author or editor to assign keys from the Document Properties
box.
This gives users the most flexibility but requires that they open the
Document Properties box and manually choose a key.
A document can be encrypted when it is first saved, or it can be encrypted
when saved after a subsequent editing session. A document cannot be
encrypted unless it contains at least one field that has been designated as
encryptable.
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. Notes 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 any of the keys used to encrypt the document, that
encryption key is used to decrypt the document.

Examples
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.
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

Chapter 8: Restricting Access to and Securing Parts of an Application 215


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 the Database Managers Guide.

Details
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 regular
documents.
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, Notes
automatically stores it in your User ID. If someone sends you an encryption
key, Notes stores the new key in your User ID, along with any other keys.
North American and International encryption keys
Notes 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.

216 Application Developers Guide


If a document is encrypted with a North American encryption key, people
using Notes outside of the United States and Canada cannot decrypt the
document because they cant add a North American encryption key to their
international IDs. 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 cant change the key to the North American
encryption scheme.

Enabling encryption for a field


You can activate 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 in Design mode.
2. Create a field or click an existing field. Then choose Design - Field
Properties. The field can be any data type.
3. Click the Options tab.
4. Select Security options: Enable encryption for this field.
5. Close and save the form.

Encrypting documents automatically


You can encrypt all encryptable fields automatically whenever someone
saves a new document composed with a form.
1. Open the form in Design mode.
2. Choose Design - Form Properties.
3. Click the Key icon (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.
For more information on encryption, see the Database Managers Guide.

Details
To encrypt all documents created with a form, you enable encryption for
one or more of its 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

Chapter 8: Restricting Access to and Securing Parts of an Application 217


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.

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 in Design mode.
2. Create a field named SecretEncryptionKey. Define it as a text or
keywords field that is editable or computed.
3. For a keywords field, 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 design pane and click Formula.
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. Click the Options tab.
7. (Optional) Select Security options: Enable encryption for this field so
unauthorized users cannot see the names of encryption keys used in the
formulas and keywords.
8. Close and save the form.
For more information on encryption, see the Database Managers Guide.

Details
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.
If the SecretEncryptionKeys field is empty (null), the document isnt
encrypted.

218 Application Developers Guide


Examples
Editable keywords 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
Dont encrypt |

Editable keywords field that lists multiple keys


This keywords 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
Dont 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 8: Restricting Access to and Securing Parts of an Application 219


About 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,
Purchasing.

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 access roles, 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 in advance


To define a list of section editors in advance, write a formula that calculates
the list of allowed editors, either by looking at 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.
Only formulas that result in a text list containing one or more names can be
used; 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 Programmers Guide.

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.

220 Application Developers Guide


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


To create an access-controlled section
1. Open the form in Design mode
2. Highlight the text, fields, and other design elements that make up the
section.
3. Choose Create - Section - Controlled Access.
4. (Optional) In the Section Properties box, edit the section title.
5. (Optional) Enter a Section Field Name.
6. (Optional) Choose a border style and border color for the section.
You can insert fields and other design elements in 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. Open the form in Design mode.
2. Click the section title.
3. Choose Section - Section Properties.
4. Click the Formula tab.
5. Select Editable as the section Type to allow the document creator to
specify the section editors.
6. Select one of the Computed types to use a formula to define the section
editors.
7. (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.

Chapter 8: Restricting Access to and Securing Parts of an Application 221


To collapse an access-controlled section
1. Open the form in Design mode.
2. Click the section marker and choose Section - Section Properties.
3. Click the Editors tab and select options for showing the section
expanded or collapsed, depending on whether a document is being
previewed, printed, or opened.
4. Click the Non-Editors tab and select options for displaying the section
to users who can read but not edit the section.
5. Select Hide title when expanded if users dont need to see the section
title when the fields are displayed.
6. Close and save the form.

Examples
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.

About attaching electronic signatures to documents and sections


For extra security, you can have Notes 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.
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 activate 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

222 Application Developers Guide


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
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.

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 Field Properties box.

Chapter 8: Restricting Access to and Securing Parts of an Application 223


About how Notes stores and verifies electronic signatures
Notes combines the data in a sign-enabled field with the private key from
the senders User ID to create a unique electronic signature. Notes stores
the signature, along with the public key and the list of certificates from the
senders ID, in the document.

Storing signatures in documents


Notes 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, Notes 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, Notes
stores the signature with the section.
If a user with Editor access in the database ACL changes a sign-enabled
section, Notes replaces the existing signature with the editors signature
when the document is resaved.
If there are several sign-enabled fields in the section, Notes 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.
For documents with several sign-enabled, access-controlled sections,
Notes 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,
Notes replaces all original section signatures with the newer signature
when resaving the document. Notes 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.

224 Application Developers Guide


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. Notes 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, Notes 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 contents 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 about certification, see Getting Started with Domino.

Chapter 8: Restricting Access to and Securing Parts of an Application 225


Chapter 9
Completing an Application

This chapter describes how to document an application and how to test it


before deployment.

About completing an application


These items are needed for any application.
A database icon
Database help
You may also want to:
Provide customized SmartIcons sets, 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 the
Database Managers Guide.

About designing the database icon


Every database should have an icon that helps users find the database
quickly on their workspaces by visually representing 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.

227
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 Notes.

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 Notes, and Notes
truncates larger bitmaps.
2. Copy the bitmap to the Clipboard.
3. Start Notes, select the database youre designing, and choose View -
Design.
4. In the navigation pane, click Design - Other.
5. Double-click Icon.
6. Click Paste and then click OK.
7. Double-click the icon to edit it.

To create a new icon


You must have a mouse to create a new icon.
1. Select the database and choose View - Design.
2. In the navigation pane, click Design - 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.

228 Application Developers Guide


About 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.
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.
Field help describes the purpose and use of individual fields.
A help view organizes and displays help documents.

About creating About and Using documents


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.
The About document should include:
The purpose of the database.
The intended audience.
The name and telephone number of the database manager.
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.

Chapter 9: Completing an Application 229


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, 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.

Creating an About or Using document


To create an About or Using document
1. Select the database youre designing and choose View - Design.
2. In the navigation pane, click Design - 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.

To automatically display the About This Database document


1. (Optional) 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.

230 Application Developers Guide


You can use the About document as a springboard to a file in another
database or another products file. 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 or Using.
Select or open a database on the workspace and choose Help -
About This Database or Using This Database.

About writing help for fields


Field help is optional, but it can help users fill out documents without
assistance. A field label 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 to be translated to another language, use
no more than 55 characters to allow the translations a few extra characters.

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.

Chapter 9: Completing an Application 231


Writing help for fields
To write field help
1. Open the form or subform in Design mode.
2. Double-click the field.
3. In the Field Properties box, click the Options tab.
4. Write a Help description.
5. Close and save the form or subform.

To write pop-up text


1. Open the form in Design mode.
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.
For more information on creating a pop-up hotspot, see Notes Help.

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 help forms as
part of the database and display them 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 design 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.

232 Application Developers Guide


About controlling what displays when the database opens
You can set database properties that control what a user sees when the
database opens. For example, you might want the About This Database
document to display to let the users know the purpose of the database. 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 a workstation, you can display:
The database as the user last viewed it
The About This Database document for the database
A navigator in the application window or 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 server, you can display:
The About This Document document
The First doclink in an About This Database document
A navigator in the application window or in its own window

Controlling what displays when the database opens


1. Select the database youre designing and choose File - Database -
Properties.
2. Click the Launch tab.
3. Do one or both of the following:
Choose what to display when the database opens on a workstation
Choose what to display when the database opens on a Web server.
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.

Details
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 Notes database. 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

Chapter 9: Completing an Application 233


To view the About This Database document, users choose Help - About
This Database or close the link or attachment.

Displaying a document preview automatically


You can automatically display a preview pane that shows the contents of
the highlighted document 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 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.

About 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 the
Database Managers Guide.

Viewing a summary of the design


Each database has a design synopsis that displays information about the
design elements in the database.
1. Select the icon for the database whose design you want to know more
about.
2. Choose File - Database - Design Synopsis.

234 Application Developers Guide


3. Select the information you want to include in the synopsis.
4. Click OK.
5. To export the synopsis, choose File - Export.
6. To paste the synopsis, choose Edit - Select All and then choose Edit -
Copy. In a Notes document or another products file, choose Edit -
Paste.
7. Close the synopsis window.

Details
Database information
Select Database to display the database title, location, categories, and so
on.
Select Space usage to display the file size, number of documents, space
used by the database, and so on.
Select Replication to display the database replication settings.
Select Access List to display a name-by-name listing of the ACL, with
the access level and access roles assigned to each.
Design information
Select Shared field to display the options chosen for each shared field in
the database.
Select Stored query to display the formula and selected options for full
text search queries saved with the database.
Select Agent to display the options and formulas chosen for each shared
and private agent.
Select Forms and select one or more forms or subforms to display the
options chosen for the component and its non-shared fields.
Select Views and select one or more views or folders to display the
options chosen for each shared view or folder and its columns, as well as
any navigators in the database.

Chapter 9: Completing an Application 235


About 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 Defaults 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.

236 Application Developers Guide


If needed, has a read-access list been defined for the form?
Define a read access list one by assigning names to a Read access
control list on the Security tab of the Form Properties box.
If needed, has a create access list been defined for the form?
Define a create access list by assigning names to a Compose access
control list on the Security tab in the Form Properties box.

About 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.
In time-date fields, is the time displaying correctly?

Chapter 9: Completing an Application 237


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.

About 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.
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.

238 Application Developers Guide


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 used 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 by selecting 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.
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.

Chapter 9: Completing an Application 239


About pilot testing an application
Once your application has been reviewed, pilot test it with a few users. To
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.

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.
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. 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 the
Database Managers Guide.

240 Application Developers Guide


About restricting design changes
Once an application is complete and ready for deployment, 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 information on restricting design changes and hiding the design of an
application, see Chapter 14.

Making a master design copy of a completed application


Before delivering the database to the database manager for general release,
make a local template copy as the master design. You can make future
design changes to the template and then transfer them to the server
database.
1. Select the database icon 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. Click Encryption to encrypt the database and protect its contents from
being accessed at the operating system level.
8. Click OK.
9. Choose File - Database - Access Control to define an appropriate
access control list for the template.
For more information about rolling out an application, see the Database
Managers Guide.

Chapter 9: Completing an Application 241


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.
The following access levels are appropriate for the access control list of a
template that you use for design maintenance:
Default: Reader
LocalDomainServers: Reader
OtherDomainServers: Reader
Your user name: Manager
Database Manager: Manager
The server that stores the database: Manager

242 Application Developers Guide


Chapter 10
Developing Applications for the Web

Web applications combine the structure and security of databases with


Internet technology. This chapter describes techniques that are specific to
developing applications for Web users.
For general information about creating and styling specific design elements,
see earlier chapters.
For lists of design features that you should avoid using in Web applications,
see Appendix D.

About developing applications for the Domino Web server


The Domino Web server allows users with Web browsers, such as Netscape
Navigator, Microsoft Internet Explorer, or Notes Web Navigator, to
participate in discussions, e-mail, research, and workflow activities that are
housed in databases. The Notes Designer gives you a single application
development environment in which to create databases for Web users,
Notes users, or both.

243
Glossary of Web terms for application developers
This glossary helps you understand Web terminology within the context of
the Notes Designer application development environment.

Home page
A home page is a special Web page that you designate as the entry point for
a Web site. It usually contains information about the site, a contents listing,
and links to other parts of the site. When you create Web databases within
Notes, you can use the Web Pages template to create home pages within a
Web pages database or choose from several methods for assigning your
sites home pages, including auto-launch About This Database documents,
auto-launch navigators, and stand-alone HTML files.

HTTP
Hypertext Transfer Protocol (HTTP) is the standard Internet protocol that
enables Web clients to access information stored on Web servers. The
Domino server speaks HTTP 1.1, enabling Web clients to communicate
with Notes servers and access databases stored on the servers. Any Domino
server can serve Web users if the Notes system administrator loads the
HTTP server task.

HTML
Hypertext Markup Language (HTML) is the code Web developers use to
format text for the Web. Each page you see on the Web uses HTML
instructions to display images and text. Domino uses HTML when it
displays database information to Web users.

URL
The Uniform Resource Locator (URL) interface is the standard Internet
protocol that enables Web clients to request specific pages from Web
servers. When you type in a URL for example, http://www.lotus.com
the Web client (your browser) sends the request to the HTTP server. Each
Web page has its own URL.
Traditional Web servers use URLs to determine which pages to display to
users. Domino servers, unlike traditional Web servers, assign URLs to
database elements to determine where data is located and how to display it
to users. You can build URLs into forms and views to automatically open
databases, views, forms, and so on. This example opens the database
webapp.nsf on a fictitious server named www.mercury.com:
http://www.mercury.com/webapp.nsf?OpenDatabase

244 Application Developers Guide


Web page
A Web page is a collection of graphics, text, and applets that can be viewed
from a Web browser. The page may be a single HTML file or several HTML
files designed to display together in one window along with any applets
associated with the page.
Domino automatically creates Web pages for Notes documents, forms,
views, navigators, applets, and other database elements. This saves you
development time because you dont have to create an HTML file for each
page you want to display. Instead, you store the design instructions, as well
as the content and applets for the pages, in a Notes database.

Web site
A traditional Web site is a collection of related HTML files that have
interconnected links which users use to jump from one file to another.
When you create Web databases within Notes, your Web site consists of
one or more databases that store the content and design of the site. Views,
navigators, hotspots, and links give users access to different parts of the
site. Web sites that you use Notes Designer for Domino to construct have
links that are dynamically generated. You do not have to code them
manually.

Glossary of Notes Designer terms for Web developers


This glossary helps you understand Notes Designer terms within the
context of a Web application development environment.

About This Database document


The About This Database document is a design element that introduces a
database. An About This Database document can be the default opening
page for a database if you design it to open automatically when a database
opens. You can include text, graphics, hotspots, HTML, applets, links,
embedded navigators, and embedded views in an About This Database
document.

Chapter 10: Developing Applications for the Web 245


Database
Every Web application uses at least one database to organize and store data
and design elements. Database file names end with .NSF and reside in the
Notes Data directory or a subdirectory of a Domino server, which is a
networked machine to which Web users have access. If youre accustomed
to Web design, the concept of a database may be unfamiliar; think of it as a
storage area for related Web pages. A Web site is a collection of databases
stored on one server.

Documents
Documents are individual Web pages that store the data for a database.
Web developers create documents to provide information about the
database or Web site. Web users create documents to participate in
discussions and workflow processes. Documents can contain text, graphics,
fields, applets, HTML, embedded navigators, and embedded views.
To create documents from the Web, users need a button that simulates the
Notes Create - <form> menu command. You can build the button into a
view, a navigator, or an About This Database document. Web users fill in
the necessary information on the form and then click the button to save the
document in the database.

Fields
A field in a document contains one piece of information, such as a persons
name, a comment, a number, a date, or the results of a calculation. When
developers create fields on forms, theyre creating a data holder for that
piece of information. In Web applications, fields also can contain Web
pages, multimedia objects, graphics, and files. The form Web users choose
when they create a document determines which fields the document
contains.

Forms
Forms are design elements that give users a framework for entering new
information in a database and for viewing existing information. They are
similar to Web input forms that solicit information from users, but are used
not only for inputting new data, but for displaying existing data. Most
databases have forms for different kinds of information. For example, a
discussion database usually includes a form to begin a new topic of
discussion and another form to respond to topics. You can associate forms
with other design elements, such as views and navigators, to create
sophisticated Web effects.

246 Application Developers Guide


Navigators
Navigators provide a graphical way for users to find documents or take
actions in an open database without having to open views. Domino
converts navigator to HTML image maps on the Web when you select the
Web browser compatible navigator property. You can also embed
navigators in forms or documents, so they display together. A navigator
can be an entry point for a database if you design it to open automatically
when a database opens.

Templates
A template is a pre-designed database that you use to create new databases
quickly. When you create a database and base its design on a template, you
receive a number of forms, views, and navigators that determine how this
database looks and functions. Templates have file names that end in .NTF.
Several Notes Designer templates are helpful for Web developers,
including:
Web Pages (R4.6) (pagesw46.ntf)
Discussion - Notes & Web (R4.6) (discsw46.ntf)
Doc Library - Notes & Web (R4.6) (doclbw46.ntf)
Frameset (R4.6) (framew46.ntf)
For more information about Notes Designer templates and sample
databases, see Appendix A.

Views
A view is the entry point for opening and reading documents. Web users
click a link to open a document. Most database designs use several views to
organize and present documents in different ways. Think of views as
HTML index files that have automatic updating functions, programming
features, and graphics.

Chapter 10: Developing Applications for the Web 247


About planning a Web site
A Web site is an organized collection of information stored in one or more
databases that reside on a Domino server. As you plan a Web site, think
about the types of databases, views, navigators, and forms youll need to
build the site.

A Quick Start Web site


Use the Web Pages (R4.6) template (pagesw46.ntf) to create a Web site that
has a home page, a Webmaster page, an upcoming events page, and a
discussion forum for site visitors.

A single-database Web site


A simple Web site includes a single database, an About This Database
document that displays each time the database opens, one or two forms and
views, and possibly a navigator. A simple Web site works well for sites that
have only one or two main functions. Examples include:
A country inn whose informational site includes pictures of the inn,
details about the facilities, a list of seasonal activities, and current
prices.
A civic interest group whose interactive site maintains a list of members
and hosts ongoing discussions about improving the community.
To build a simple Web site, create a database from a template. Then create
some pages, including a home page.

A multi-database Web site


A large Web site includes several databases, each with its own forms,
views, and navigators, bound by document, view, and database links that
make the multi-database organization invisible to users. The databases at
such a site may also contain agents that process documents automatically.
This approach works well for sites that have several functions or that
contain interrelated databases. Examples include:
A commercial site where customers can browse product catalogs, place
credit-card orders, learn how to use products, and mail ideas for new
products to specific departments or divisions.
A Human Resources site where employees can search for benefit
information, learn about changes to existing benefits, initiate requests
for follow-up appointments with HR representatives, and view custom
information about the components of their personal benefits packages.

248 Application Developers Guide


To create a multi-database Web site, use Domino.Action, which is included
with the Domino server, to get started with several Web-ready databases
right away. You can also purchase Lotus Domino.Applications for other
specialized purposes, such as news distribution, electronic commerce,
document management, and data-linking with other database systems. For
purchasing information, see the Lotus Web site at http://www.lotus.com.

About Web settings in the Server document


The HTTP Server section of the Server document in the Public Address
Book maintains several settings pertinent to Web applications, including the
server home page, graphic display formats, and character set choices. The
Notes system administrator is responsible for managing these settings, but
its helpful to familiarize yourself with them because several may affect the
display of a Web application.
For more information on the Server document, see Getting Started with
Domino.

About Web site home pages


A home page gives users a logical entry point to and a summary of the
information in a Web site. 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 show the organization of the 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
Although you can use an HTML file as a home page for your Domino site,
the Notes Designer environment lets you produce attractive home pages
quickly. Create an About This Database document or a regular document
with links to views, documents, or navigators in the same database or other
related databases at the site. Store the home page in a database whose only

Chapter 10: Developing Applications for the Web 249


purpose is to store the home page or in a database used for other purposes,
such as discussions, user registration, or product information. If your site
contains multiple databases, decide which one should store the site home
page.
To set the home page to launch automatically, choose File - Database -
Properties, click the Launch tab, and select the appropriate On Web Open
option.
For home page ideas, see the Domino 4.6 sample databases installed with
the Notes Designer templates.

About specifying the Web site home page in the Server document
To make a Notes 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 database document, navigator, or
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

250 Application Developers Guide


About Web databases
A Web database, in its simplest form, is identical to a Notes database. What
makes it a Web database is the viewing mechanism a Web browser
instead of a Notes workstation and the fact that it resides on a Domino
server running the HTTP server task. You do all database design work in
the Designer and use Notes design elements forms, fields, views,
navigators to display and organize the content.
When you design a database for the Web, keep in mind that:
Databases viewed from a Web browser may look somewhat different
than they do when viewed from a Notes workstation. Each browser
dictates some of the display qualities.
You must supply form and view actions for menu commands, such as
Create and Edit. Web users dont have menus for database activities in
their browsers.
You may want to take advantage of Internet technology that isnt
applicable to Notes workstations to enhance the look or the operation of
a Web database.

Migrating Notes databases to the Web


To migrate an existing Notes database to the Web, do the following:
Install and set up the Domino server.
Make sure the database is in the Notes Data directory or a subdirectory
of the Data directory.
Modify the database ACL to designate access levels for Web users.
Add form actions to simulate menu commands, such as Create, Edit,
and Save. Display the form actions in the action bar.
Remove or hide features that arent supported on the Web.
Select the database property Web access: Use JavaScript when
generating pages.
Set up text searching.
You may also want to create a site home page that contains links to other
Web databases on the server, and add features that enhance the appearance
of the database.
For more information, see sections later in this chapter and Appendix D.

Chapter 10: Developing Applications for the Web 251


Specifying an opening page for Web databases
To help users understand how to use a database, add a document or
navigator that launches when Web users open a database and that contains
instructions for finding and creating information.

To use the Web Pages template


If youre creating Web pages in a database whose design is based on the
Web Pages template (pagesw46.ntf), designate one as the opening page.
1. Open the Pages view.
2. Open the page you want to specify as the opening page in the Pages
view.
3. Select the Make this page the home page checkbox.
This adds a link to this page from the About This Database document,
which is set to launch the first document link automatically when Web
users open the database.

To use On Web Open options


The Database Properties - Launch tab offers several options for customizing
the opening of any database.
Use Notes launch option
Domino uses the On Database open setting by default.
Open About database document
Uses the About This Database document as the opening page.
Open designated Navigator in its own window
Uses the selected navigator as the opening page.
Launch first doclink in About database
Uses the first document linked to the About This Database document as
the opening page.
Launch designated doclink
Uses a document from any database on the server as the opening page.
Use Edit - Copy as Link - Document Link to copy the document to the
clipboard, select Launch designated doclink from the On Web
Open list, then click Paste Doclink.
Launch first document in view
Uses the first document from the selected view as the opening page.

252 Application Developers Guide


About creating Web content
The Domino server automatically converts all design elements and
documents to Web pages. Therefore, by creating a database with views,
navigators, and forms, and documents, you create Web pages. If youre just
getting started, create a database from the Web Pages template
(pagesw46.ntf) and use the Page form to create Web content quickly. To
enhance the appearance of Web pages, add embedded navigators, views,
and folders to forms or add applets, computed text hotspots, hotspot
images, and HTML code to forms and documents.

About previewing your design work on the Web


As you design applications, you can preview how they will look to Web
users. Notes Designer displays the element using the Internet browser
named in the current Location document of your Personal Address Book.
To preview documents, choose Actions - Preview in Web Browser.
To preview shared views, choose Actions - Preview in Web Browser.
To preview forms and navigators in design mode, choose Design -
Preview in Web Browser.
(You cannot preview views in design mode.)
To shut down the HTTP process that runs the Web Browser preview
without exiting Notes, choose File - Tools - Stop Local Web Preview
Process.

Requirements
Windows 95 or NT workstation
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 Web documents, navigators, and
views. One of those entries needs Author access to let you preview Web
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.
Set up your browser(s) to override proxy settings (described below).

Chapter 10: Developing Applications for the Web 253


To set up your 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.
1. In Notes, choose File - Open - Edit Current Location.
2. Next to Web Proxy, click the Hat 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.
1. Open each browser, and then open its Proxy settings page:
In Internet Explorer, choose View - Options, Connection, Proxy
settings.
In Netscape Navigator 3.0, choose Options - Network Preferences -
Proxies.
2. Specify these case-sensitive entries:
localhost
<Domino server name>
3. Click OK.

Hiding features from Web or Notes users


Notes Designer offers several ways to hide and display information in a
database thats used by both Notes and Web users.

To hide design elements


You can hide forms, views, navigators, folders, subforms, and agents. This
allows you to hide features that arent supported or are irrelevant in a
particular environment for example, views used for keywords field
lookups or forms used by agents. If you have two versions of design
elements (a Web version and a Notes version), give them the same name or
alias. Hide one from Notes users and hide the other from Web users.
Domino displays the correct version based on the users system.

254 Application Developers Guide


1. Choose View - Design to open the toolbox, then click the design
element type (forms, views, navigators, folders, subforms, agents).
2. Click the name of the design element you want to hide and choose
Design - Design Properties (or for agents, Agent - Agent Properties).
3. Click the Hide tab and select Hide design element from Web
browsers or Hide design element from Notes R4.6 or later clients.
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, use parentheses around the
design element name as in, (Lookup View) instead of using Hide tab
options.

To hide parts of a design element


Hide text, graphics, fields, layout regions, form and view actions, and so on
in the Properties box. This is useful for hiding Web features for example,
HTML code from Notes users and for hiding Notes features for
example, layout regions from Web users.
1. With the form or view in design mode, select the element you want to
hide and choose Design - <element> Properties or for text, choose Text -
Text Properties.
2. Click the Hide tab and select Hide from Notes R4.6 or later or Hide
from Web Browsers.
3. Close and save the design element.
Tip Use the menu command View - Show - Hidden from Notes to
reveal any text you hide from Notes users within a document, so you can
edit it from a Notes workstation.

Chapter 10: Developing Applications for the Web 255


About Web documents
When users open a document from the Web, Domino converts it to an
HTML page. The page contains the design of the form used to create the
document with its fields, text, graphics, and the action bar and the
documents data. Domino automatically generates its own <BODY> and
<HEAD> tags for each page, unless you select the form property, For Web
access: Treat document contents as HTML or use HTML attributes to
override the defaults.
These screens compare how a document appears to Netscape Navigator
users and Notes users.

256 Application Developers Guide


About creating new documents on the Web
Since Web users dont have access to Notes menu commands, you must
design buttons or form and view actions into Web databases to allow users
to create, edit, and save documents. When Web users create a new
document, they enter information into editable fields just as they do in
Notes.
These screens compare how a new document appears to Netscape
Navigator users and Notes users.

Chapter 10: Developing Applications for the Web 257


Adding computed text to a document or form
Use computed text in documents and forms to generate text based on
formula results. This is useful for creating dynamic text in Web and Notes
documents. Add computed text in a rich text field of a document in Edit
mode or on a form in Design mode.
1. Place the cursor where you want the computed text to appear.
2. Choose Create - Computed Text.
3. Write a formula whose value displays the text you want to show in the
document or form.

Examples
The Our Companys Web Site document in the Site 3 Samples database
(site3w46.nsf) uses computed text and HTML code to find an image file
within the current database.

The computed text (shown with a border in the figure above) uses the
formula:
tmpDb
to return the value of the field whose formula:
@Subset(@DbName;-1)
generates the name of the database.

Creating an attachments field for Web documents


To allow Web users to attach files to documents, include a File Upload
Control on the form.
1. Open the form in design mode, place the cursor where you want the
field to appear, and choose Create - Web Element - File Upload Control.
2. Open the Properties box for the field and on the Hide tab, select Hide
paragraph from Notes R4.6 or later.
Then when Web users open the document in edit mode, they can attach a
file by typing the path and file name in the field or clicking Browse to select
a file. Domino saves the attachment with the document. Not all browsers
support this feature.

258 Application Developers Guide


About Web views and folders
Each time a Web user opens, scrolls, expands, or collapses 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
Notes view doesnt apply to a Web view.

Standard views
Unless you use HTML formatting to customize a view, it maintains the
column and row format of standard Notes views, but with these
differences:
Domino generates a Web navigation bar at the top and bottom of the
screen. This navigation bar contains buttons that users click to expand,
collapse, and scroll the view.
Users open documents by clicking a document-link column rather than
clicking anywhere in the row.
Compare the Discussion view shown through Netscape Navigator with the
same view shown through Notes.

Chapter 10: Developing Applications for the Web 259


Multi-line column headings and multi-line rows
To prevent line wrap, 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.

Calendar views
Web users can see all calendar entries. Domino converts calendar views to
HTML tables. Therefore, Domino restrictions for tables also apply to
calendar views. Conflict bars and the clock are not supported on the Web,
nor are creating new appointments and scrolling through entries within a
single day.

Folders
Web users cannot drag documents into folders.

260 Application Developers Guide


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 cant revert to
Dominos default behavior you must continue to designate at least one
linking column.
1. Click the column(s) you want to display as linking columns.
2. Open the Column Properties box and click the Advanced (hat) tab.
3. Select For Web Access: Show values in this column as links.

About Web navigators


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 image map. All 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.
If you do not select Web browser compatible for the navigator, Domino
displays a graphic background, hotspot polygons, rectangles, and circles,
but no other objects.

About displaying views and navigators with documents


By embedding a view, the folder pane, or a navigator in a form or
document, you create an assortment of ways to navigate a database from
Web documents. The Designer templates contain numerous examples of
forms designed in this way, including Discussion - Notes & Web (R4.6)
template, Doc Library - Notes & Web (R4.6), and the Site Samples
Databases.
Embedded elements you can include are:
Folder pane
Displays a list of views and folders with the standard Folders
navigator, as seen in Notes with the View - Show Folders command.
The font style you apply to the field applies to the style used to display
the folders.
Embedded view
Displays a view within a document.

Chapter 10: Developing Applications for the Web 261


Embedded navigator
Displays a navigator within a document.
This example from the Doc Library template contains two embedded
navigators and an embedded view.

The Frameset (R4.6) template (framew46.ntf) provides another way to


create multiple windows for a document. For more information, see Best
Practices: Templates and Sample Databases on the Notes.Net Web site.

Embedding a view, folder pane, or navigator


1. Open a form in Design mode or open a document in Edit mode.
2. Place the cursor where you want the embedded element to display.
3. Choose one of the following:
Create - Web Element - Embedded View
Create - Web Element - Embedded Folder Pane
Create - Web Element - Embedded Navigator
4. (Optional, for views and navigators) If you dont want to display the
same embedded element in all circumstances, click Choose a View
based on a formula or Choose a Navigator based on a formula.

262 Application Developers Guide


When you click OK to close the dialog box, write a formula in the
design pane to display the appropriate view or navigator.
5. (Optional) Click the embedded element and choose Pane - <web
element> Properties to change the alignment or style, or to hide the
element under certain conditions.
6. Close and save the form or document.
To change which embedded view or navigator displays in the form, click
the element and choose another view or navigator from the list in the
design pane.
To delete an embedded view or navigator, click the element and choose
Edit - Clear.

Details
A form can have only one embedded view and one embedded folder pane.
You can embed navigators and views anywhere on a document, form, or
subform, including in tables, as part of collapsed sections, and as left-,
right-, or center-aligned design elements.
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 view opening if there are create or read access
lists on a form in which views are embedded.
$$ Fields
For compatibility with previous releases, the reserved fields $$ViewBody,
$$ViewList, and $$NavigatorBody still work. The fields must be text fields
that are editable or any computed type. You can combine these fields on the
same form for example, one $$ViewBody field, one $$ViewList field, and
several $$NavigatorBody fields.
Field name Value Comments
$$ViewBody View name (in quotes) or Same as Embedded View.
a formula that computes
the view name
$$ViewList None Same as Embedded Folder Pane.
$$NavigatorBody, Navigator name (in Same as Embedded Navigator. To
$$NavigatorBody_n quotes) or a formula that create multiple $$NavigatorBody
computes the navigator fields on a form, append an
name underscore and a character to
each subsequent field name.

Chapter 10: Developing Applications for the Web 263


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 Formula
Next @DbCommand(Domino; ViewPageUp)
Prev @DbCommand(Domino; ViewPageDown)
Expand @Command([ViewExpandAll])
Collapse @Command([ViewCollapseAll])
Search @Command([ViewShowSearchBar])

Using a form as a view or navigator template


In Web applications, to create an association between a form and a view or
navigator, assign a reserved name to the form. Domino uses the form when
users open the view or navigator. Use the following reserved form names to
create an association between a form and a view or navigator.
Form name Design element required Comments
$$ViewTemplate Embedded view or Associates the form with a specific
for viewname $$ViewBody field view. The form name includes
viewname, which is the alias for the
view or when no alias exists, the name
of the view. For example, the form
named $$ViewTemplate for By
Author associates the form with the
By Author view.
Domino requires an Embedded View
or the $$ViewBody field on the form,
but ignores the value.
continued

264 Application Developers Guide


Form name Design element required Comments
$$Navigator Embedded navigator or Associates the form with a specific
Template for $$NavigatorBody field navigator. The form name includes
navigatorname navigatorname, which is the navigator
name. For example, the form named
$$Navigator Template for World
Map associates the form with the
World Map navigator.

Domino requires an embedded


navigator or the $$NavigatorBody
field on the form, but ignores the
value. Domino ignores create and read
access lists on the form.
$$ViewTemplate Embedded view or Makes this form the template for all
Default $$ViewBody field Web views that arent associated with
another form.

Domino requires an embedded view


or the $$ViewBody field on the form,
but ignores the value.
$$Navigator Embedded navigator or Makes this form the template for all
TemplateDefault $$NavigatorBody field Web navigators that arent associated
with another form.

Domino requires an embedded


navigator or the $$NavigatorBody
field on the form, but ignores the
value.

Overriding an embedded navigator with a navigator template


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

Chapter 10: Developing Applications for the Web 265


About Web buttons and actions
Web users dont have access to Notes menu choices when they work in
databases. Therefore, for Web applications, you should design form and
view actions that display in the action bar or buttons that display with
documents as menu equivalents.
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.
Be aware that Domino displays all buttons, actions, and hotspots even
those that contain @commands and @functions that arent supported for
Web applications.
For more information, see About using @commands in Web applications
and About using @functions in Web applications later in this chapter.

About providing menu replacements for Web users


Web users dont have access to Notes menus because they use a browser to
access databases. To allow Web users to create and edit documents, add
hotspots, links, or actions that display in the action bar.
Use @command formulas in action bar buttons to enable users to create
documents and open views.
This formula opens a new Main Topic in the current database:
@Command([Compose];Main Topic)
To compose a document, use the syntax:
@Command([Compose]; formname)
@Command([Compose];:database; formname)
To open a view, use the syntax:
@Command([OpenView]; viewname)
@Command([OpenView];:database; viewname)
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.

266 Application Developers Guide


About adding HTML to a Web application
To add Web-specific instructions or formatting to databases, use your own
HTML code in forms, documents, fields, views, columns, and agents.
Domino combines the HTML instructions with the data and passes it to the
browser for display.
Domino supports most tags in the HTML 3.2 spec, as well as additional
tags not in the spec. For information about HTML 3.2, visit this site:
http://www.w3.org/pub/WWW/MarkUp/Wilbur/
For information on writing HTML code, visit the HTML Spec Web site at:
http://www.w3.org/pub/WWW/MarkUp/

Formatting documents with HTML


The Form event HTML Body Attributes lets you attach HTML formatting
attributes to all documents created with the form. This event modifies the
<BODY> tag attributes that Domino automatically assigns to Web
documents.
1. With the form in design mode, click the name of the form in the Define
list and select HTML Body Attributes in the Event list.
2. Write the HTML code in quotes in the window below for example:
BACKGROUND=/images/backgr.gif
3. Close and save the form.

Typing HTML directly on a form or document


Use Pass-Thru HTML formatting to flag text in a form or document as
HTML-only.
1. Enter the text you want formatted as HTML code.
2. Select the text and choose Text - Pass-Thru HTML.
3. With the text selected, choose Text - Text Properties.
4. (Optional) Click the Hide tab and choose Hide paragraph from: Notes
R4.6 or later.
5. Choose Text - Pass-Thru HTML again to return to regular formatting.
6. Close and save the form or document.
To edit the text later from a Notes workstation, choose View - Show -
Pass-Thru HTML, or if you hid the text from Notes users, choose View -
Show - Hidden from Notes.

Chapter 10: Developing Applications for the Web 267


Treating documents as pure HTML
When you select the Treat documents as HTML form property, Domino
converts all data on the document, the form, and subforms, to HTML.
Domino ignores embedded navigators and folders and any embedded
views that dont have the property Treat view contents as HTML
selected.
1. With the form in Design mode, choose Design - Form Properties.
2. Click the Defaults tab and select For Web Access: Treat documents as
HTML.
3. Close and save the form.

Adding HTML attributes to a field


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. Select HTML Attributes in the Event list.
3. Write the HTML code in quotes in the edit window for example,
SIZE=40 MAXLENGTH=40
4. Close and save the form.

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 a form. Use HTML code as the
field value either in the form or when you use the form to create
documents. This is similar to 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. With a form in design mode, create a field named HTML.
2. Select Value or Default Value in the Event list.
3. (Optional) Write the HTML code in the edit window if you want to
present the same HTML code for every document created with the
form.
4. Close and 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.

268 Application Developers Guide


Details
The field can be computed or editable, but editable is the most likely choice
if you want to change the HTML on a per-document basis, rather than
create it once for a whole form. Use a text field for HTML text that is less
than 15K; otherwise, use a rich text field.

Adding HTML header information to Web documents


If you dont use the For Web Access: Treat document contents as HTML
form property, adding a $$HTMLHead field to a form allows you to pass
HTML information, such as Meta tags and JavaScript, to the Head tag for a
document. The field can be any data type, but a hidden
computed-for-display text field is the best choice.
This technique does not work directly on About This Database documents
because Domino generates its own Head tags when it displays About This
Database documents. To work around this, you can create a regular
document with a form that contains a $$HTMLHead field and add a link to
the document from the About This Database document that launches
automatically when the database opens.

Examples
The following examples use a $$HTMLHead field in a database.
Adding a Meta tag
A $$HTMLHead field with the following formula adds the Meta tag
keyword with a value of gold to the Head tag in a document.
<meta name=\keyword\ content=\gold\>

Using JavaScript and Cookies to load a page into the browser


This example displays a message that shows the number of times a user has
visited the site. It uses a $$HTMLHead field, a program stored in the CGI
programs directory, and HTML on the form. The program uses JavaScript
and cookies to load a page into the browser and save a cookie called
Cookie_Man in the users cookie file.
Code for the $$HTMLHead field
The $$HTMLHead field contains the following value. Quotation marks
( ) must be preceded by \.
<script>
cookieName = \Cookie_Man\;
function doCookie() {
if(document.cookie) {
index = document.cookie.indexOf(cookieName);

Chapter 10: Developing Applications for the Web 269


} else {
index = -1;
}
if (index == -1) {
document.cookie=cookieName+
\=1; expires=Tuesday, 01-Apr-1997 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=Tuesday, 01-Apr-1997 08:00:00 GMT\;
}
}
function getTimes() {
if(document.cookie) {
index = document.cookie.indexOf(cookieName);
if (index != -1) {
countbegin = (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 {

270 Application Developers Guide


return (\<b>\+count+\</b> times
before.</b>\);
}
}
}
return (\<b>0</b> times before.</b></b>\);
}
</script>

Code on the form


The HTML Body Attributes form event contains the following code:
onLoad=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>

Using HTML formatting for views


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 displays
as a standard view. On the Web, the view uses the HTML formatting
attributes you specify in the column formula. You must include HTML that
defines all formatting and document linking for the view. You must select
this property to display a Web view that is embedded in a form that has the
For Web Access: Treat document contents as HTML selected.
1. Open the view in Design mode and choose Design - View Properties.
2. Click the Advanced (hat) tab and select For Web Access: Treat view
contents as HTML.
3. Create a column.
4. In the design pane, click Formula and write the HTML code in the edit
window.

Adding pass-thru HTML to a column


To insert HTML in a column, click Formula in the design pane and add
HTML as the column value. Notes users also see the HTML when it is used
in a view they can see.

Chapter 10: Developing Applications for the Web 271


The following formula inserts the graphic NEW.GIF if the document was
created within the last five days; otherwise, no graphic is displayed.

Embedding HTML in agent scripts


An agent written in LotusScript can include the Print statement to display
HTML information to a user or give instructions to the browser. Agents
used this way must be manually run shared agents, activated with a button,
action, or WebQuerySave or WebQueryOpen event that uses
@Command([ToolsRunMacro]).
This line, added to the end of a LotusScript program, displays the message
Thank you for your submission when the agent runs:
Print <H1>Thank you for your submission</H1>
Printing a URL enclosed in square brackets causes the browser to navigate
to that URL. This line causes the browser to go to the Domino site when the
agent runs:
Print [http://domino.lotus.com]

About Web graphics and colors


You can paste or import graphics into documents, forms, views, and
navigators. Domino stores graphics in a platform-independent 256-color
format that is similar to GIF89a format. (GIFs are 256-color images.) When
Web users open a database, Domino converts the stored graphics to one of
two Web formats: Graphics Interchange Format (GIF) or Joint Photographic
Experts Group (JPEG). The Notes system administrator specifies the format
in the Image conversion format field, which is part of the HTTP Server
section of the Server document.

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 Notes client or a Web browser
Operating system Macintosh, Windows NT, Windows 95, OS/2, or
UNIX
Color mode 16-color mode, 256-color mode or High/True/24-bit
color mode

272 Application Developers Guide


How many colors and which colors?
Always reduce graphics 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. 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. 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 the Lotus color palette.
If your audience is only Web users, use the Web color palette.
If your audience is both Notes and Web users, you can:
Use black and white or very simply-colored graphics.
Use the Lotus color palette.
For most colors, it also works well on the Web.
Create two graphics one for Notes users and one for Web users.
Use the appropriate palette for each graphic and hide the graphic
from the audience that wont use it.

Finding the Lotus and Web color palettes


The Lotus color palette (lotus.pal or lotus.act, depending on which palette
your graphics program accepts) is available on the Web from the
Application Development Best Practices Guide, in the topic called
Guidelines for handling color in your application. You can download the
guide from:
http://www.lotus.com/devtools/2106.htm
The Web color palette (bclut2.aco), developed by Lynda Weinman, is
available at her Web site:
http://www.lynda.com/files/

Which graphics format?


When you create graphics for Notes users, use any of the graphics file
formats supported by Domino JPEG, GIF, BMP, TIFF, and so on. Because
Web browsers support GIF and JPEG formats directly, many developers
find it easier to design graphics using these formats.

Chapter 10: Developing Applications for the Web 273


Adding background graphics
You can place background graphics on a form, on individual documents, or
on navigators.
To allow users or Web content authors to customize background colors or
graphics for individual documents, set the form background property
Allow users to override background properties. If a form contains a
background graphic, a document author can substitute another background
for an individual document without changing the default form background.
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.

Sizing graphics
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 in Notes.

Importing and pasting graphics


In most cases, pasting and importing work equally well. However, if you
paste a graphic and it doesnt display the way you expect, try choosing
either:
Edit - Paste Special and choose Bitmap
File - Import

Adding text descriptions to graphics and applets


Adding text descriptions allows users with text-only Web browsers to
visualize the graphics and applets that the browser cannot display. For
users with graphical Web browsers, text descriptions serve as placeholders
for graphics and applets that the browser is loading.
1. Select the graphic and choose Picture - Picture Properties or select the
applet and choose Java Applet - Java Applet Properties.
2. Under Alternate text for Web and deferred loading, type descriptive
text that summarizes the function of the graphic or applet.

274 Application Developers Guide


About Web fonts and styles
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,
Helvetica and Times Roman 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 Notes 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 Maps to HTML Size


7 1
9 2
11 3 (this is the default size)
13 4
17 5
23 6
greater than 23 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.

Chapter 10: Developing Applications for the Web 275


Text colors
Web users see the same approximate text colors as Notes users, but the
colors may not match exactly.
For more information about colors, see About Web graphics and colors
earlier in this chapter.

About Web agents


Agents written in LotusScript or Java run on Web databases. Web
agents run if they are activated by a schedule, new mail, or pasted
documents. Buttons, hotspots, and form and view actions use the
@Command([ToolsRunMacro]) or the OpenAgent URL command to
run agents.
When agents run, they automatically check the identity of a Notes user
against any Server document or ACL restrictions. Manually-run agents run
with the identity of the Notes user; scheduled agents run with the identity
of the person who created or last modified the agent. Since Web users dont
have a Notes ID that identifies them, you must choose Agent - Agent
Properties, click the Design tab, and select For Web Access: Run Agent as
Web user.

About running agents 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.

276 Application Developers Guide


WebQuerySave events
A WebQuerySave event runs the agent before the document is actually
saved to disk. The agent can modify the document or use the document
data to perform other operations.
Examples for using this agent include:
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.

About setting up security for Web applications


Every database has an access control list (ACL) that defines who can access
it and what tasks users can perform. After you design a Web application,
discuss the confidentiality requirements with the database manager, who is
responsible for defining the ACL. To define security for a Web site, set up
the ACL for each database that is part of the site.
You can include the following in the ACL:
Users and servers with Notes IDs
Registered Web users whose names and passwords are stored in the
Public Address Book
Groups that list Web users, Notes users, and servers
For more information, see the Database Managers Guide.

Access control lists and Web databases


The access control list contains three sections that are relevant to Web
databases.
The general access level for each person, server, or group
The tasks each person, server, or group can perform
The maximum level allowed to Web users

Access levels for Web databases


The access levels for a database are:
No Access Users cannot access the database.

Chapter 10: Developing Applications for the Web 277


Depositor Users can create documents but cant see any documents,
including the documents they create. This access is useful for survey
responses or ballot boxes.
Reader Users can read documents in a database but cant create or edit
documents. If Web users havent already been prompted for their name or
password during an HTTP session, when they open a database whose
Default access is Reader or higher, they are classified as anonymous users.
Author Users can create documents and edit documents they create.
Editor Users can create documents and edit all documents, including those
created by others.
Designer Users can change the design of databases.
Manager Users can modify ACL settings and perform all tasks allowed by
other access levels. Notes requires at least one Manager for a database, but
its best to assign two people Manager access.
The server needs to be part of an entry named Anonymous or have Default
access in the database access control list to show previews of documents,
navigators, and views. It needs Author access to show previews of forms.

Task restrictions for Web users


To further refine a users or groups access level, allow or restrict these
specific tasks for each user, group, or server entry in the access control list:
Creating documents
Deleting documents
Creating personal agents
Creating personal folders/views
Creating shared folders/views
Creating LotusScript agents
Reading public documents
Writing public documents
For most databases, you should allow Web users to create and delete
documents. Other tasks, such as creating folders and views and creating
agents, do not apply to Web users.

Maximum access for Web users


Each database has a maximum access level for Web users, defined in the
Advanced section of the access control list. Even if the database access
control list explicitly gives individual Web users higher access, they never
have an access level greater than what you specify as the Maximum
Internet name & password access level.

278 Application Developers Guide


The default is Editor access. To grant all Web users access to a database,
select Reader or higher. To prevent any access by Web users, select No
access.
For more information, see the Database Managers Guide.

Setting up the access control list for a Web database


1. Select the database and choose File - Database - Access Control.
2. Assign yourself and at least one other Manager to the access control list
and give yourselves access to all tasks.
3. Set an access level for the - Default - entry.
4. Add entries for Notes and Web users, groups, and servers and set their
access levels.
5. (Optional) Add an entry called Anonymous to set a specific access
level for Web users who havent registered at the site that is, for Web
users who dont have Person documents in the Public Address Book.
6. (Optional) Refine the entries by restricting or allowing individual tasks.
7. Click Advanced and accept or change the Web access level in the
Maximum Internet name & password access list.
8. Click OK.
For more information, see the Database Managers Guide.

Examples
ACL for high-security confidential database

Default No access
Anonymous No access
Authorized readers Reader
Contributors Author
Supervisors Editor
Maximum Internet name & password access Reader
ACL for medium-security project database
Default Reader
Anonymous No access
Authorized readers Reader
Project team members Editor
Maximum Internet name & password access Editor

Chapter 10: Developing Applications for the Web 279


ACL for low-security informational database
Default Reader
Anonymous Reader
Contributors Author
Supervisors Editor
Maximum Internet name & password access Editor

ACL for low-security discussion database


Default Author
Anonymous Author
Supervisors Editor
Maximum Internet name & password access Editor

Setting up roles for a Web database


Roles are database-specific groups that you create to simplify the
maintenance of restricted fields, forms, and views. You can apply the role
to Authors fields, Readers fields, and read and create access lists in forms
and views.
1. Select the database and choose File - Database - Access Control.
2. Click Roles and choose Add to create a new role.
3. Click Basics and highlight the names of people, groups, or servers that
should be included in the role.
4. Click OK.
For more information, see the Database Managers Guide.

About restricting access to Web views, forms, and fields


To restrict who can see or change specific information on a Web site, you
can restrict access to specific views and documents with create and read
access lists for views and forms.
Note Web users can see encrypted fields. Do not rely on encrypted fields
as a way to restrict access for Web users.
For more information on restricting access, see Chapter 8.

280 Application Developers Guide


About enforcing encrypted Web transactions for a database
The Secure Sockets Layer (SSL) is a security protocol that protects data by
encrypting it as it passes between servers and Web clients. To set up SSL at
the server, the system administrator enables the SSL port in the Server
document, creates an SSL certificate, and distributes the certificate to Web
users.
To protect transactions in individual databases such as, those used for
commercial transactions select the database property Web access:
Require SSL Connection. To open SSL-protected databases, Web users
must include the SSL certificate in their browser configuration.
For more information, see Getting Started with Domino.

About setting up links within a Web site


To help users maneuver through the Web site, create links to documents,
views, and databases.

Linking to documents, views, and databases


Use the Edit - Copy As Link command to add a link that lets users switch to
a document, an anchor within a document, a view, a folder, or a database.
Domino converts these links to Hypertext links on the Web. These links are
more stable than traditional HTML links because they do not reference file
names; rather, they reference the unique internal ID of a database, view, or
document. If the name of the linked item changes, the link remains valid.
To customize the look of Notes links, add text or a graphic as the link, select
it, and choose - Create Hotspot - Link Hotspot.

Linking to URLs
To add a link to an external site, use Create - Hotspot - URL Link to create a
URL in a document or form.

Chapter 10: Developing Applications for the Web 281


About setting up Web searching
To help users find the documents theyre interested in quickly and easily,
set up a site to allow text searching in a single view or in multiple
databases. To search for specific information, a user clicks a Search link or
button, enters criteria in a form, and submits the form. Then Domino
returns a list of links to documents that match the criteria. Searching works
only on text in Notes documents, not on text in HTML or other types of
files.
For information on customizing the search form, see About customizing
search forms and search results later in this chapter.

Setting up view searches


Searching a view is appropriate for text searches that involve only one
database. To set up view searching for a database, do the following at a
Notes workstation:
1. Create a full text index for the database.
2. Add HTML to a view or form that includes a SearchView URL
command.
For more information, see About URL commands for searching for text
later in this chapter.

Setting up multiple-database searches


The scope of a multiple-database search can include all the databases on a
Domino server or virtual server site or be limited to a group of related
databases. You may want to create several search site databases for the
different types of searches you expect for a site. For example, a search
generated from a home database view might search every database at the
site; a search generated from a Product Support database might search only
technical information databases.
To set up a multiple-database search at the site, do the following at a Notes
workstation:
1. Use the Search Site template to create a search site database.
2. Create Search Scope documents to configure the search scope.
3. Select Include in multi-database indexing on the Design tab of the
Database Properties box or select the database in the Server
Administration - Database Tools window and enable the Multi
Database Indexing Tool.
4. Create a full text index for the search site database.

282 Application Developers Guide


This indexes all databases included in the search scope. You dont need
to create full text indexes for individual databases unless you want
users to be able to perform view searches as well.
5. Add HTML to a view or form that includes a SearchSite URL
command.
For more information, see About URL commands for searching for text
later in this chapter.
Full text indexes take up disk space. If you enable searching for many
databases or for several large databases, you may need to increase the
storage capacity of the Domino server. For more information about full text
indexes, see the Database Managers Guide. For more information about
setting up multiple-database searching and setting up full text indexing
schedules, see Getting Started with Domino.

About customizing search forms for Web users


To customize searching at your site, add your own design touches to search
input and search results forms.

Customizing search input forms


When a user initiates a text search from the Web, Domino looks in the
current database or in the search site database in a multiple-database search
for a form with the actual name or the alias name $$Search. If the form
exists, Domino opens it; otherwise, Domino displays the default search.htm
file stored in the domino\icons directory.
Domino provides two Notes forms in the Search Site database for
user-defined searches:
Web Search Simple ($$Search is the alias name) is a Designer version of
search.htm that has a link to the Web Search Advanced form.
Web Search Advanced allows users to create detailed searches based on
multiple words and phrases, categories, or dates. It includes a link to
the Web Search Simple form.
You can copy these forms to any search site database or to any database
that allows view-level searches. Use them as is, or customize them for each
search. You can also customize the default search.htm form.

Chapter 10: Developing Applications for the Web 283


Customizing search results forms
To customize the Search Results page, create a form and assign it one of the
form names shown in the following table. Then add a field named
$$ViewBody to the form.
The following features in the default Search results form provided with
Domino cant be built into a customized Search results page:
A count of the number of documents found
The ability to restate the search query
A search bar that allows users to reset search results.
Form name Field required Comments
$$SearchTemplate for $$ViewBody Associates the form with a
viewname specific view. Domino requires
the $$ViewBody field, but
ignores the value. The form
name includes viewname, which
is the alias for the view, or, when
no alias exists, the name of the
view. For example, the form
named $$SearchTemplate for
All Documents associates the
form with the All Documents
view.
$$SearchTemplateDefault $$ViewBody Domino requires the
$$ViewBody field, but ignores
the value. This form is the
default for all Web searches that
arent associated with a specific
form.

284 Application Developers Guide


Examples
This sample shows a customized Search results page for all views.

About customizing the Webs Form processed confirmation


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>);

Chapter 10: Developing Applications for the Web 285


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]

About customizing Web error message forms


To customize the appearance of error messages that display to Web users,
add custom error message forms to the database. If an error condition
occurs and a custom form exists for it, Domino uses the custom form to
display the error message. Otherwise, Domino uses the default error
message form. Message forms that you add to a database override any
server-wide messages set up by an administrator.
To create the association between a form and an error condition, create a
form with the one of the following names. Then create an editable text field
named MessageString to hold the error message. Add any additional text,
graphics, links, and so on that you want displayed with the message.

286 Application Developers Guide


Form name Displays to Web users when...
$$ReturnDocumentDeleted The user successfully deletes documents
$$ReturnAuthenticationFailure The users name and password cant be
verified
$$ReturnAuthorizationFailure The user doesnt have a high enough access
level to access the database
$$ReturnGeneralError Any other errors occur

About customizing the Submit button for Web forms


If you dont select the database property Web access: Use JavaScript when
generating pages, Domino places a Submit button at the bottom of each
Web document by default. Users click the Submit button to save and close a
document. To customize the default location or appearance of the Submit
button, you can relabel or move the button or replace it with a graphic.
1. Choose File - Database - Properties and select Web access: Use
JavaScript when generating pages.
2. Do one of the following:
Move or rename the Submit button. Add a button to the form where
you want users to see it and label the button Submit or use a label of
your choice.
Use a graphic as a Submit button. Paste the graphic into the form,
select the graphic, and choose Create - Hotspot - Action Hotspot.
3. Attach this formula to the button or hotspot:
@Command([FileSave]);
@Command([FileCloseWindow])

About using @functions in Web applications


For information about @functions that shouldnt be used for Web
applications, see Appendix D.
Keep the following in mind when you include write formulas that include
@functions.

Write conditional formulas based on the type of user


To write formulas that depend on whether the user is a Web user or a
Notes user, use @ClientType in formulas for computed subforms, hotspots,

Chapter 10: Developing Applications for the Web 287


actions, and hide-when formulas to display Web-only information. The
return value is Notes for a Notes user and Web for a Web user.

Avoid formulas that reference a selected document


Document selection isnt applicable to the Web; therefore, default value
formulas cannot reference a selected document in the view.

Avoid using @Now and @DocumentUniqueID


Avoid relying on values based on time such as @Now and
@DocumentUniqueID because they may be updated a second time
during a Web transaction.
To simulate an @Unique formula, use @DocumentUniqueID and compute
an extra value, such as an incremental integer, to make a unique value.

About using @commands in Web applications


Most @commands are based on the Notes workstation user interface and
are not applicable to the Web. These are the only @commands that you can
use in Web applications.

Supported @command Comments


@Command([CalendarFormat])
@Command([CalendarGoTo])
@Command([Compose]) The Server argument does not
apply, but you must specify it as a
null string: ().
@Command([EditClear]) Deletes the current document. Use
only for form actions; not
supported in view actions.
@Command([EditDocument]) Edits the current document. Use
only for forms; not supported in
view actions.
@Command([EditInsertFileAttachment]) This @command is disabled when
Web buttons are enabled with the
Web access: Use JavaScript when
generating pages database
property. Using Create - Web
Element - File Upload Control
achieves the same effect.
continued

288 Application Developers Guide


Supported @command Comments
@Command([FileCloseWindow)] Supported when the database
property Web access: Use
JavaScript when generating
pages is enabled. Use the
command by itself to simulate the
Notes File - Close command to
return the user to a view or an
open database. Precede the
command with
@Command([FileSave]) to
simulate a Submit button.
@Command([FileOpenDatabase]) The server argument must be
specified as a null string ().
@Command([FileSave]) Supported when the database
property Web access: Use
JavaScript when generating
pages is enabled. Use with
@Command([FileCloseWindow])
to simulate a Submit button.
@Command([NavigateNext]) Use only for forms; not supported
@Command([NavigatePrev]) in view actions.
@Command([NavigateNextMain])
@Command([NavigatePrevMain])
@Command([OpenNavigator])
@Command([OpenView])
@Command([OpenView]; ViewName; key)
@Command([ToolsRunMacro])
@Command([ViewChange]) Works like OpenView, but the
view name must be included.
@Command([ViewExpandAll])
@Command([ViewCollapseAll])
@Command([ViewShowSearchBar])
@Command([ViewRefreshFields]) Supported when the database
property Web access: Use
JavaScript when generating
pages is enabled. Recalculates all
field formulas without closing the
document.
@DbCommand(Domino;ViewNextPage) Creates a link to the
@DbCommand next/previous page in a view.
(Domino;ViewPreviousPage)

Chapter 10: Developing Applications for the Web 289


About 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.

About Common Gateway Interface (CGI) programs


CGI is a standard for connecting external applications with HTTP servers.
CGI programs allow you to do some background processing on 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.

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.

About 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.

290 Application Developers Guide


For more information about CGI variables, see Table of CGI variables
later in this chapter.

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.

Using the DocumentContext property in Web agent scripts


The DocumentContext property of the NotesSession class is useful in
Web-run LotusScript agents. The property returns a Notes document that
contains all CGI variables that are applicable to the session, as well as the
values of the document being opened or saved. 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.

Examples
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)

Chapter 10: Developing Applications for the Web 291


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.
For more information about CGI environment variables, see:
http://hoohoo.ncsa.uiuc.edu/cgi/env.html
Field name Returns
Auth_Type If the server supports user authentication and
the script is protected, this is the
protocol-specific authentication method used
to validate the user.
Content_Length The length of the content, as given by the
client.
Content_Type For queries that have attached information,
such as HTTP POST and PUT, this is the
content type of the data.
Gateway_Interface The version of the CGI spec with which the
server complies.
HTTP_Accept The MIME types that the client accepts, as
specified by HTTP headers.
HTTP_Referer The URL of the page the user used to get here.
HTTPS Indicates if SSL mode is enabled for the
server.
HTTP_User_Agent The browser that the client is using to send the
request.
Path_Info 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.
Path_Translated The server provides a translated version of
PATH_INFO, which takes the path and does
any virtual-to-physical mapping to it.
Query_String The information that follows the ? in the URL
that referenced this script.
Remote_Addr The IP address of the remote host making the
request.
continued

292 Application Developers Guide


Field name Returns
Remote_Host The name of the host making the request.
Remote_Ident This variable will be set to the remote user
name retrieved from the server. Use this
variable only for logging.
Remote_User Authentication method that returns the
authenticated user name.
Request_Method The method used to make the request. For
HTTP, this is GET, HEAD, POST, and
so on.
Script_Name A virtual path to the script being executed,
used for self-referencing URLs.
Server_Name The servers host name, DNS alias, or IP
address as it would appear in self-referencing
URLs.
Server_Protocol The name and revision of the information
protocol accompanying this request.
Server_Port The port to which the request was sent.
Server_Software The name and version of the information
server software running the CGI program.
Server_URL_Gateway_Interface The version of the CGI spec with which the
server complies.

About the Domino URL commands


A URL command combines a specific URL with a command that
manipulates the item. Adding Domino URL commands as HTML in forms
gives users shortcuts for navigating databases and performing tasks
quickly.

The Domino URL command syntax


Domino URL commands have the syntax:
http://Host/NotesObject?Action&Arguments
Where
Host = a DNS entry or an IP address
NotesObject = a Notes construct (For example, a database, view,
document, form, navigator, agent, and so on.)

Chapter 10: Developing Applications for the Web 293


Action = the desired operation on the specified Notes object (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.
Special identifiers used in Domino URL commands include:
$defaultView, $defaultForm, $defaultNav, $searchForm, $file, $icon,
$help, $about, and $first.
NotesObject can be any of the following: for a database, the database
name or replica ID; for other objects, the Notes objects 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 objects name and universal ID are identical in all replicas of a
database, but the Notes objects NoteID will probably change in
database replicas. Therefore, it is best to use the Notes object 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.
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
Separate arguments with & (ampersand). For example:
http://www.mercury.com/leads.nsf/By+Salesperson?OpenView&
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

294 Application Developers Guide


About URL commands for opening servers, databases, and views
The following commands access servers, databases, views, About This
Database documents, Help documents, and database icons. 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
Example
http://www.mercury.com/?OpenServer

OpenDatabase
Syntax
http://Host/DatabaseFileName?OpenDatabase
http://Host/DatabaseReplicaID?OpenDatabase
Examples
http://www.mercury.com/leads.nsf?OpenDatabase
http://www.mercury.com/sales/discussion.nsf?OpenDatabase
http://www.mercury.com/852562F3007ABFD6?OpenDatabase

OpenView
Syntax
http://Host/Database/ViewName?OpenView
http://Host/Database/ViewUniversalID?OpenView
http://Host/Database/ViewNoteID?OpenView
http://Host/Database/$defaultview?OpenView
Examples
http://www.mercury.com/leads.nsf/By+Salesperson?OpenView
http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F300702
264?OpenView
http://www.mercury.com/leads.nsf/00000196?OpenView
http://www.mercury.com/leads.nsf/$defaultview?OpenView

Chapter 10: Developing Applications for the Web 295


Optional arguments for OpenView
Append optional arguments to refine the URL. Combine any of the
following arguments for the desired result.
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, subtopic 5,
document 1).
Count = n
Where:
n is the number of rows to display
ExpandView
Displays the view in expanded format
CollapseView
Displays the view in collapsed format
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.
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.
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/00000196?OpenView&ExpandView
http://www.mercury.com/leads.nsf/00000196?OpenView&Start=3&
Count=15
http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F300702
26400000196?OpenView&CollapseView

296 Application Developers Guide


http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F300702
26400000196?OpenView&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

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

About URL commands for opening forms, navigators, and agents


The following commands open forms, navigators, and agents in a database.
Hidden design elements are hidden from the server too; you cant use
Domino URL commands to access documents in hidden forms.

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

Chapter 10: Developing Applications for the Web 297


http://www.mercury.com/products.nsf/625E6111C597A11B852563DD007
24CC2?OpenForm
http://www.mercury.com/products.nsf/0000024A?OpenForm
http://www.mercury.com/products.nsf/$defaultform?OpenForm

Optional arguments 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/40aa91d55cle4c8285256363004dc9
e0?OpenForm&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.
Examples
http://www.mercury.com/products.nsf/Main+Navigator?OpenNavigator
http://www.mercury.com/products.nsf/7B5BC17C7DC9EB7E85256207004
F8862?OpenNavigator
http://www.mercury.com/products.nsf/000001AA?OpenNavigator
http://www.mercury.com/products.nsf/$defaultNav?OpenNavigator

OpenAgent
Syntax
http://Host/Database/AgentName?OpenAgent
http://Host/Database/AgentUniversalID?OpenAgent

298 Application Developers Guide


Examples
http://www.mercury.com/sales/leads.nsf/
Process+New+Leads?OpenAgent
http://www.mercury.com/sales/leads.nsf/D28E9F105AA6BDD585256324
006D5F5D?OpenAgent

About URL commands for opening, editing, and deleting 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.

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/35AE8FBFA573336A852563
D100741784?OpenDocument
http://www.mercury.com/leads.nsf/By+Region/
0000229E?OpenDocument

EditDocument
Syntax
http://Host/Database/View/Document?EditDocument
Example
http://www.mercury.com/products.nsf/By+Part+Number/
PC156?EditDocument

Chapter 10: Developing Applications for the Web 299


DeleteDocument
Syntax
http://Host/Database/View/Document?DeleteDocument
Example
http://www.mercury.com/products.nsf/By+Part+Number/
PC156?DeleteDocument

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
Example
http://www.mercury.com/products.nsf/b9815a87b36a85d9852563df004a9
533?CreateDocument

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/a0cefa69d38ad9ed8525631b00658
2d0/4c95c7c6700160e2852563df0078cfeb?SaveDocument

About URL commands for opening documents by key


The following commands allow you to open a document by key, 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

300 Application Developers Guide


Where:
View is the name of the view.
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.
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.
(EditDocument and DeleteDocument must be explicit commands.)
Example
http://www.mercury.com/register.nsf/Registered+Users/
Jay+Street?OpenDocument

Using @Commands to link to a document


Use @Commands in an action, button, or action hotspot to link to
documents by key. To do this, the action formula must combine two
@commands: one to select the document and one to open the document. To
select the document, use the key argument with the [OpenView] or
[FileOpenDatabase] @commands. To open or edit the document, use
@Command([OpenDocument]). Both of these @commands must be present
in order for Domino to generate the appropriate URL.
Syntax
@Command([OpenView];ViewName;key);
@Command([OpenDocument])
Alternative syntax:
@Command([FileOpenDatabase];:DatabaseName;ViewName;key);
@Command([OpenDocument])
Examples
@Command([OpenView];Registered Users;@UserName);
@Command([OpenDocument])
Alternative syntax:
@Command([FileOpenDatabase];:Register.nsf;Registered
Users;@UserName);

Chapter 10: Developing Applications for the Web 301


@Command([OpenDocument])
To refine the @Command, append the optional argument for
[OpenDocument] 1 to edit; 0 to read.
Note Only the @Command combinations listed above are valid. For
example, you cannot combine
@Command([OpenView];ViewName;key);
@Command([EditDocument])

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/$Fi
le/DOMINO.EXE
ViewUNID can indicate a ViewID or a ViewName. DocumentUNID can be a
NotesID or a DocumentKey. This allows you to create URL links to
attachments by supplying a view name and document key, for example
By default, the browser uses the name specified in the URL to save the file.

About URL commands for opening image files, attachments, and


OLE objects
The following commands open files and objects within a document.

OpenElement
Use the ?OpenElement command to access file attachments, image files, and
OLE objects.

Using OpenElement with file 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 that 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.

302 Application Developers Guide


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?OpenElement
&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.

Using OpenElement with OLE Objects


Syntax
http://Host/Database/View/Document/FieldName/FieldOffset/$OLEOBJINFO/
FieldOffset/obj.ods?OpenElement
Note that 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.

About URL commands for searching for text


Search-related URLs are available for view searches and multiple-database
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. You can also define a URL that performs text searches
without user input.
For more information about creating search databases, see Creating a
searchable site earlier in this chapter.

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:

Chapter 10: Developing Applications for the Web 303


$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.
Example
http://www.mercury.com/products.nsf/By+Product+Number/
$SearchForm?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.
ArgumentList= Query=string&SearchOrder=n&SearchThesaurus=True or
False&SearchMax=n&;SearchWV=True or False
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
SearchOrder=[1,2,3]
Where 1 = Sort by relevance, 2 = Sort by date ascending, 3 =Sort by
date descending. The default is 1.
SearchThesaurus=[TRUE, FALSE]
Where the default is FALSE, which means Do not use thesaurus synonyms
in the search.
SearchMax=[n]

304 Application Developers Guide


Where n is the maximum number of entries returned. 0 (return all entries) is
the default.
SearchWV=[TRUE, FALSE]
Where the default is TRUE, which means Include word variants in the
search.
Examples
http://www.mercury.com/mercsrch.nsf/?SearchSite&Query=product+inf
o+requests&SearchOrder=2&SsearchMax=30&SearchWV=TRUE&SearchTh
esaurus=TRUE
http://www.mercury.com/products.nsf/By+Product+Number/
?SearchView&Query=PC156&SearchOrder=3&SearchMax=1

About 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.

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

Chapter 10: Developing Applications for the Web 305


About URL commands for processing SSL certificates
The following commands automate the request and receipt of Secure
Sockets Layer (SSL) certificates stored in a database.
For more information, see Planning the Domino System.

OpenForm with SpecialAction argument


Syntax
http://Host/Database/FormName?OpenForm&SpecialAction=specialAction
Field
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 About URL
commands for opening forms, navigators, and agents earlier in this
chapter.

Examples
http://www.mercury.com/certs.nsf/UserCertificateRequest?OpenForm
&SpecialAction=SubmitCertField
http://www.mercury.com/certs.nsf/ServerCertificateRequest?OpenForm
&SpecialAction=ServerRequestField
http://www.mercury.com/certs.nsf/Certificate?OpenForm
&SpecialAction=ServerPickupField

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=SubmitCert
&TranslateForm=TranslationFormName
Where:
ResultForm is a form in the specified database that displays information
about the processed request.

306 Application Developers Guide


TranslationFormName represents a form in the database that contains
fields to hold certificate information.
Example
http://www.mercury.com/certs.nsf/CertificateProcessed?RequestCert
&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.
Syntax
http://Host/Database/MessageForm?RequestCert
&Command=ServerRequest&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.

Chapter 10: Developing Applications for the Web 307


Example
http://www.mercury.com/certs.nsf/CertificateProcessed?RequestCert
&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 into
the document if the form contains fields with these names:
CommonName
Org
OrgUnit
Locality
State
Country

About editing the HTTPD.CNF file to add MIME type mappings


HTTPD.CNF is the configuration file for your Internet system. You can use
this file to specify MIME (Multimedia Internet Mail Extension) type
mappings a process that maps an attachments file extension (for
example, .WAV for sound files) to an external viewer or a helper
application. When you include MIME type mappings in HTTPD.CNF,
Domino reads the extension of the attached file and sends the appropriate
information to the browser.
The syntax for specifying MIME type mapping is:
Addtype .extension type/subtype/ encoding [quality[ character-set]]
For example, to allow a QuickTime video clip attached to a Notes
document to play on a users machine, specify the MIME type mapping in
the Domino Web servers HTTPD.CNF file:
AddType .mov video/quicktime binary 1.0 # Quicktime
When Web users click the QuickTime clip, Domino sends the MIME type
mapping video/quicktime to the browser.

308 Application Developers Guide


The following table contains a sample of MIME type settings in a
HTTPD.CNF file:
AddType .mime www/mime binary 1.0 # Internal
MIME is
AddType .bin application/octet-stream binary 1.0 #
Uninterpreted
binary
AddType .oda application/oda binary 1.0
AddType .pdf application/pdf binary 1.0
AddType .ai application/postscript 8-bit .5 # Adobe
Illustrator
AddType PS application/postscript 8-bit .8 # PostScript
AddType .eps application/postscript 8-bit .8
AddType .ps application/postscript 8-bit .8
AddType .rtf application/x-rtf 7-bit 1.0 # RTF

Chapter 10: Developing Applications for the Web 309


Chapter 11
Including Java Applets in Applications

This chapter describes adding Java applets to forms or documents. Use Java
applets to enhance a document or Web page.

About including Java applets in applications


A Java applet is a Java program that can be included in a Notes application.
You can insert a Java applet directly on a form to include the applet in each
document created from the form, or you can insert the applet in a rich text
field of