Você está na página 1de 573

Lotus Domino Designer

Version7

Application Development with Lotus Domino Designer

G210-2369-00
Note: Before using this information and the product it supports, read the information in "Notices" at the end of this document.

First Edition (December, 2005)


This edition applies to IBM® Lotus® Domino® Designer 7 (product number L-GHUS-5RWNHM), and to all subsequent releases
and modifications, until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 1994, 2005. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents
Chapter 1. Introduction to Domino Planning a Web application . . . . . . . . . 21
Designer . . . . . . . . . . . . . . 1 Tips for designing Web applications . . . . . 22
Overview -- applications and databases . . . . . 1 Creating formulas and buttons for the Web . . . 22
Applications . . . . . . . . . . . . . 1 Planning an application for mobile users . . . . 23
Databases . . . . . . . . . . . . . . 1 Hide-when options for all applications . . . . . 23
Starting Lotus Domino Designer . . . . . . . . 2 To set hide-when options on one or more
To start Domino Designer from the Bookmark bar elements according to client type . . . . . . 23
in the Notes client . . . . . . . . . . . 2 To set hide-when options on individual elements
To start Domino Designer from a database in the according to context . . . . . . . . . . 23
Notes client . . . . . . . . . . . . . . 2 HTML tag attributes for a Domino server . . . . 24
To start Domino Designer from the command line 2 HTML tag attributes . . . . . . . . . . 24
Exploring Lotus Domino Designer . . . . . . . 3 Domino applets . . . . . . . . . . . . . 25
Properties boxes . . . . . . . . . . . . 5 Designing an application for maximum accessibility 25
Creating a database . . . . . . . . . . . . 6 Design considerations for accessible applications 25
Displaying, collecting, and storing information . . . 6 Creating multilingual applications . . . . . . . 27
Pages . . . . . . . . . . . . . . . . 6 Setting a default language and region . . . . 27
Forms and documents . . . . . . . . . . 7 Creating multilingual design elements . . . . 27
Fields . . . . . . . . . . . . . . . . 8 Translating an application using IBM Domino
Organizing your data . . . . . . . . . . . 9 Global Workbench . . . . . . . . . . . 27
Views . . . . . . . . . . . . . . . . 9 Adding translation components to a Designer
Folders . . . . . . . . . . . . . . . 9 application . . . . . . . . . . . . . 29
Creating navigation. . . . . . . . . . . . 10 Table of Notes and Domino known limits . . . . 30
Outlines . . . . . . . . . . . . . . 10
Navigators . . . . . . . . . . . . . . 11 Chapter 3. Creating an application . . . 31
Structuring your display . . . . . . . . . . 11 Creating databases . . . . . . . . . . . . 31
Adding automation . . . . . . . . . . . . 11 Creating a database from a template . . . . . 31
Actions . . . . . . . . . . . . . . . 12 Copying an existing Domino database . . . . 32
Hotspots . . . . . . . . . . . . . . 12 To create a new database by copying an existing
Agents . . . . . . . . . . . . . . . 12 database . . . . . . . . . . . . . . 33
Sharing, locking, and editing design elements . . . 12 To copy individual design elements . . . . . 33
Editing multiple design elements . . . . . . 12 To protect individual design elements . . . . 34
Sharing resources across databases . . . . . 12 Starting a database from scratch . . . . . . 34
Locking documents and design elements . . . 13 Organizing your application . . . . . . . . . 35
Autosaving Notes documents . . . . . . . . 13 Creating a bookmark on the Bookmark bar . . . 35
Enabling AutoSave in forms . . . . . . . . 13 Copying a design element to a new location . . 36
Enabling AutoSave in the Notes client . . . . 13 Creating folders for bookmarks or design
Recovering documents saved with the AutoSave elements . . . . . . . . . . . . . . 36
feature . . . . . . . . . . . . . . . 14 Using toolbars . . . . . . . . . . . . . 37
Other Autosave options . . . . . . . . . 14 Enabling subscriptions . . . . . . . . . . . 37
Extending access to applications . . . . . . . 14 Reducing database maintenance with shared code
Using third-party design tools . . . . . . . 14 and shared resources . . . . . . . . . . . 38
Using WebDAV for remote development . . . 15 Sharing file resources . . . . . . . . . . . 39
Accessing external data sources from a field . . 15 To create a file resource . . . . . . . . . 39
Bringing an application off-line . . . . . . . 15 To open a file resource. . . . . . . . . . 39
Instant messaging colleagues . . . . . . . 15 To refresh a file resource . . . . . . . . . 40
Communicating across platforms . . . . . . . 15 To prevent a file resource from being refreshed 40
JavaServer pages . . . . . . . . . . . 15 To copy a file resource to your computer . . . 40
XML. . . . . . . . . . . . . . . . 16 To delete a file resource . . . . . . . . . 40
To set up a file resource for use on the Web . . 40
Chapter 2. Planning an application . . . 17 Creating an image resource . . . . . . . . . 41
Planning a Notes application . . . . . . . . 17 To create a shared image resource . . . . . . 41
Planning a Notes and Web application . . . . . 17 To set image resource properties . . . . . . 41
Understanding the differences . . . . . . . 17 Basics tab . . . . . . . . . . . . . . 41
Tips for designing Notes and Web applications 18 Design tab . . . . . . . . . . . . . . 41
Planning for integration with WebSphere and DB2 21 To colorize grays . . . . . . . . . . . 42

iii
To insert an image resource . . . . . . . . 42 To format a section . . . . . . . . . . . 56
To insert an image resource from a file in the To delete a section . . . . . . . . . . . 56
current database . . . . . . . . . . . . 42 Creating links . . . . . . . . . . . . . 57
To rename an image resource . . . . . . . 42 To create a Named Element link . . . . . . 57
To delete an image resource . . . . . . . . 42 To copy and paste a link . . . . . . . . . 57
To reference an image resource with HTML . . 43 To create a link using the properties box . . . . 57
To make design changes to an image resource . . 43 To create a link to a document, view, anchor, or
Exporting an image resource . . . . . . . 43 database . . . . . . . . . . . . . . 57
Distributing design changes for an image . . . 43 To create a URL link . . . . . . . . . . 58
Creating a custom letterhead . . . . . . . 43 Using graphics . . . . . . . . . . . . . 58
Creating image resource sets. . . . . . . . . 43 Preparing graphics . . . . . . . . . . . 58
To create a horizontal image set . . . . . . 44 Changing the color palette . . . . . . . . 59
To create a vertical image set . . . . . . . 44 Adding graphics to a page, form, or subform . . 59
To use the image set on the Web . . . . . . 45 Changing the display properties of the graphic 60
Document locking . . . . . . . . . . . . 45 Adding a background color or graphic . . . . 60
To allow document locking . . . . . . . . 45 Adding an applet . . . . . . . . . . . . 61
To prevent document locking . . . . . . . 45 Creating an attachment . . . . . . . . . . 61
Customizing twisties . . . . . . . . . . . 45 Embedding elements . . . . . . . . . . . 62
Previewing your design work . . . . . . . . 46 To embed an element . . . . . . . . . . 62
To preview in Notes or in the default Web To delete an embedded element . . . . . . 62
browser using the menu . . . . . . . . . 46 Embedding a date picker . . . . . . . . . 62
To preview in Notes or in the default Web Embedding an Instant Messaging Contact List . . 63
browser using the preview icons . . . . . . 46 Inserting a JavaScript library . . . . . . . . 63
To set up a default browser for previewing . . . 47 To insert a JavaScript library in-line . . . . . 63
To override proxy settings for additional To Insert a JavaScript Library into the JS Header: 63
browsers . . . . . . . . . . . . . . 47 Using HTML on a page, form, or subform . . . . 63
Requirements for previewing your design work To convert pages, forms, or subforms into HTML 64
on the Web . . . . . . . . . . . . . 47 To import HTML . . . . . . . . . . . 64
Adding instant messaging to an application . . . 47 To paste HTML . . . . . . . . . . . . 64
Preventing users from accessing forms and views in To enter HTML directly on a page, form, or
a Web application . . . . . . . . . . . . 48 subform . . . . . . . . . . . . . . 65
To restrict users from opening parts of an To include some HTML on a page, form, or
application using URL commands . . . . . 48 subform . . . . . . . . . . . . . . 65
Setting launch properties for pages or forms . . . 65
Chapter 4. Designing pages . . . . . . 49 To set the launch property for a page . . . . . 65
How pages compare to forms . . . . . . . . 50 To set the launch property for a form . . . . . 65
Creating pages . . . . . . . . . . . . . 50 Layers . . . . . . . . . . . . . . . . 66
To create a page . . . . . . . . . . . . 50 Creating a layer . . . . . . . . . . . . 66
To delete a page . . . . . . . . . . . . 51 Changing the position of a layer . . . . . . 67
Displaying a page . . . . . . . . . . . . 51 Changing the HTML properties of a layer . . . 69
Creating a home page for an application . . . . 52 Changing the background color and image for a
To set the home page to launch automatically . . 52 layer. . . . . . . . . . . . . . . . 69
To specify a default home page for a Web server 52 Creating style sheets as shared resources . . . . 70
Styling text for the Web . . . . . . . . . . 52 To create a new style sheet resource . . . . . 70
Fonts . . . . . . . . . . . . . . . 52 To insert a style sheet resource into a page, form,
Size . . . . . . . . . . . . . . . . 53 or subform . . . . . . . . . . . . . 70
Preserving spaces . . . . . . . . . . . 53 To edit a style sheet resource . . . . . . . 71
Text colors . . . . . . . . . . . . . . 53 To refresh a style sheet resource . . . . . . 71
Creating computed text . . . . . . . . . . 53 Table of supported CSS properties . . . . . . 71
Example: Computed text . . . . . . . . . 53 Programming a page or form . . . . . . . . 73
Changing all text styles . . . . . . . . . . 54 Adding HTML header information . . . . . . 73
Creating and formatting horizontal rules . . . . 54 To add HTML header information . . . . . . 73
To create a horizontal rule . . . . . . . . 54 Example: Adding HTML to the Head tag . . . 73
To change the style of a horizontal rule . . . . 54 Adding JavaScript header information . . . . . 73
Creating programmable tables . . . . . . . . 54 To add JavaScript header information. . . . . 73
How programmable tables work . . . . . . 55 Example: Adding JavaScript header information 73
To create a programmable table . . . . . . . 55
Example: Creating hotspots to control a Chapter 5. Designing forms . . . . . . 75
programmable table . . . . . . . . . . 55 Form elements . . . . . . . . . . . . . 75
Creating sections . . . . . . . . . . . . 56 Forms and documents . . . . . . . . . . . 77
To create a section . . . . . . . . . . . 56 Storing a form with each document . . . . . 78

iv Application Development with Domino Designer 7


To store a form with each document . . . . . 78 Creating a layout region . . . . . . . . . 91
Overriding the stored form . . . . . . . . 78 To create a layout region . . . . . . . . . 91
Shared fields and documents with stored forms 78 To delete a layout region . . . . . . . . . 92
Form formulas . . . . . . . . . . . . 78 Aligning and rearranging elements in a layout
Designating a default form for a database . . . 79 region . . . . . . . . . . . . . . . 92
Alternatives to storing forms . . . . . . . 79 Changing the size and style of a layout region. . 92
Creating and deleting forms . . . . . . . . . 79 Adding graphics to a layout region . . . . . 92
To create a new form . . . . . . . . . . 79 Embedded controls . . . . . . . . . . . . 93
To copy an existing form . . . . . . . . . 79 Creating an embedded file upload control . . . 93
Special types of forms . . . . . . . . . . 79 Creating an embedded scheduler . . . . . . 93
To delete a form . . . . . . . . . . . . 79 Creating an embedded editor . . . . . . . 96
Tips for designing forms . . . . . . . . . . 80 Profile forms . . . . . . . . . . . . . . 97
Naming forms . . . . . . . . . . . . . 80 Creating a profile form . . . . . . . . . 98
Name requirements . . . . . . . . . . . 80 Forms that prompt users for input . . . . . . . 98
Creating aliases . . . . . . . . . . . . 80 Designing a form that presents a dialog box . . . 99
To add an alias . . . . . . . . . . . . 81 Guidelines for designing a form that presents a
Form names and keyboard shortcuts . . . . . 81 dialog box . . . . . . . . . . . . . . 99
Ordering forms on the Create menu . . . . . 81 Designing a form that prompts users for
To create a cascading menu for Notes clients . . 81 information . . . . . . . . . . . . . . 100
To move a form to the Create - Other menu in Examples: Using @Prompt . . . . . . . . 100
the Notes client . . . . . . . . . . . . 82 [YesNoCancel] . . . . . . . . . . . . 100
To remove a form from the Create menu in the [OkCancelEdit] . . . . . . . . . . . . 100
Notes client . . . . . . . . . . . . . 82 [OkCancelList] . . . . . . . . . . . . 100
To hide a form . . . . . . . . . . . . 82 Designing a form that lets users make selections
Making a form available to Web browsers . . . . 82 from a view . . . . . . . . . . . . . . 100
To make a form available to Web users . . . . 82 Using @PickList . . . . . . . . . . . 101
Selected form properties . . . . . . . . . . 83 Example . . . . . . . . . . . . . . 101
To open the Form Properties box . . . . . . 83 Designing a form for a Domino billing application 101
Protecting author/editor anonymity . . . . . 83 To specify which documents to track . . . . 101
Changing form focus . . . . . . . . . . 83 Designing a form for contact printing . . . . . 101
Handling replication conflicts . . . . . . . 83 Example . . . . . . . . . . . . . . 104
Opening documents in edit mode automatically 83 Customizing the ″Form processed″ confirmation
Choosing a content type for Web access . . . . 84 for Web users . . . . . . . . . . . . . 105
Generating HTML for hidden fields . . . . . 84 To add users’ names to the response . . . . 105
Using data sources on a form . . . . . . . 84 To link to another page . . . . . . . . . 105
To define a header on a form . . . . . . . 84 To display a different Web page . . . . . . 105
To display a graphic in a header . . . . . . 85 Displaying a customized error message on the Web 105
To create a print header and footer . . . . . 85 Adding the message field . . . . . . . . 105
Header and footer alignment . . . . . . . 85 Customizing search forms . . . . . . . . . 106
Creating a response hierarchy . . . . . . . . 85 Customizing search input forms . . . . . . 106
To create a response or response-to-response Searching for Header Information (search by
form . . . . . . . . . . . . . . . . 86 Date Created or Modified) . . . . . . . . 107
To include a parent document in a new Customizing Domain search results forms . . . 108
document . . . . . . . . . . . . . . 86 How SearchResults and
Version tracking . . . . . . . . . . . . . 86 ResultEntry/DetailedResultEntry are used . . . 108
To designate a form for version tracking . . . . 86 Customizing Web SearchView results . . . . 109
Customizing a form’s window title . . . . . . 88 Using navigational buttons for paged results 110
To customize a form’s window title . . . . . 88 Tips for improving document display time . . . 111
Examples: Customizing window titles . . . . 88 Designing forms . . . . . . . . . . . 111
Title includes creation date and company name 88 Designing fields . . . . . . . . . . . 111
Title includes number of responses . . . . . 88 Testing a form before deploying it . . . . . . 112
Response includes the subject . . . . . . . 88
Using subforms . . . . . . . . . . . . . 89 Chapter 6. Designing fields . . . . . 113
To create a subform. . . . . . . . . . . 89 Creating a single-use field . . . . . . . . . 113
To insert a subform on a form . . . . . . . 90 To copy fields . . . . . . . . . . . . 113
To display a computed subform on a form . . . 90 To delete fields . . . . . . . . . . . . 113
Example of displaying a computed subform . . 90 To convert a shared field to a single-use field 114
Deleting subforms . . . . . . . . . . . 90 To convert a single-use field to a shared field 114
To delete a subform from a form . . . . . . 90 Creating a shared field . . . . . . . . . . 114
To delete a subform from a database . . . . . 90 To create a shared field . . . . . . . . . 114
Layout regions . . . . . . . . . . . . . 91 To insert a shared field . . . . . . . . . 114

Contents v
To rename a shared field . . . . . . . . 114 To add HTML attributes using the Field
To delete a shared field . . . . . . . . . 115 Properties box: . . . . . . . . . . . . 139
To convert a single-use field to a shared field 115 To add HTML attributes using the field’s HTML
To create multiple shared fields for different Attributes event: . . . . . . . . . . . 139
languages . . . . . . . . . . . . . 115 Storing HTML in a field . . . . . . . . . . 140
Field names and labels . . . . . . . . . . 116 Creating fields that inherit values . . . . . . 140
Naming a field . . . . . . . . . . . . 116 To create a field that inherits values from
Renaming a field . . . . . . . . . . . 116 another document . . . . . . . . . . . 140
Field types . . . . . . . . . . . . . . 116 Example: Inheriting address information . . . 140
Text, rich text, and rich text lite fields . . . . . 117 To create a field that inherits an entire
Displaying graphics, attachments, and objects in document . . . . . . . . . . . . . 141
a rich text field . . . . . . . . . . . . 117 To Inherit information in a response hierarchy 141
Using rich text lite fields. . . . . . . . . 117 Standard fields used in templates . . . . . . 141
Rich text fields on the Web . . . . . . . . 118 Predefined fields with built-in functionality . . . 142
Number fields . . . . . . . . . . . . . 120 Reserved names for embedded elements . . . 142
Numeric fields . . . . . . . . . . . . 120 Reserved fields for use in billing applications 142
Currency fields . . . . . . . . . . . . 121 Reserved fields for general use . . . . . . 142
Date/Time fields . . . . . . . . . . . . 121 Internal fields on forms . . . . . . . . . 143
Choosing a Date/Time format . . . . . . . 121 Reserved fields that control mailing options . . . 143
To display a date . . . . . . . . . . . 121 Table of fields that control mailing options . . 143
To display a time . . . . . . . . . . . 122 Interactions with the Mail Send dialog box . . 144
Formulas for Date/Time fields . . . . . . . 123 Interactions with the Document Save dialog box 144
Creating a graphical display for Date/Time MailFormat . . . . . . . . . . . . . 144
fields . . . . . . . . . . . . . . . 124 MailOptions . . . . . . . . . . . . . 144
Names fields . . . . . . . . . . . . . 125 SendTo . . . . . . . . . . . . . . 145
Looking up names for field values . . . . . 126 Fields for version tracking . . . . . . . . . 145
Lookup options . . . . . . . . . . . 126 To create a computed $VersionOpt field . . . 145
Enabling a field for instant messaging . . . . 126 To create a choice list $VersionOpt field . . . 145
Readers and Authors fields . . . . . . . . . 126 Designing fields that prompt users to select folders 146
Creating fields to display lists of choices . . . . 127
Generating choices for lists . . . . . . . . . 128 Chapter 7. Designing framesets . . . 147
Use View dialog for choices . . . . . . . 128 Creating a frameset . . . . . . . . . . . 147
Examples: Creating a field to display a list of Using the View menu with framesets . . . . 148
choices . . . . . . . . . . . . . . 129 Providing content for a frame . . . . . . . . 148
Creating a formula-generated list . . . . . . 129 Setting the style for frames . . . . . . . . . 149
Creating aliases for choices in a list . . . . . . 129 Specifying a target frame . . . . . . . . . 151
Converting aliases to full category names . . . 129 Launching a database into a frameset . . . . . 152
Example: Using aliases for choices in a list . . 130 Launching a page or form into a frameset . . . . 152
Password fields. . . . . . . . . . . . . 130 Launching a view or folder into a frameset . . . 152
Example: Using an input translation formula 130
Example: Using a QuerySave event . . . . . 130
Chapter 8. Designing views . . . . . 155
Example 2: Using a QuerySave event . . . . 131
Folders . . . . . . . . . . . . . . . 155
Formula fields . . . . . . . . . . . . . 131
Standard outline views . . . . . . . . . . 155
Color fields . . . . . . . . . . . . . . 132
Displaying a view on the Web . . . . . . . 157
Time zone fields . . . . . . . . . . . . 133
Limits for views . . . . . . . . . . . 157
Editable and computed fields . . . . . . . . 133
Calendar views . . . . . . . . . . . . . 157
Writing field formulas . . . . . . . . . 133
Shared and private views . . . . . . . . . 158
Computed field formulas . . . . . . . . 133
Shared views . . . . . . . . . . . . 158
To create a formula for the value of a computed
Shared, contains documents not in any folders 158
field . . . . . . . . . . . . . . . 134
Shared, contains deleted documents . . . . . 158
Editable field formulas . . . . . . . . . 134
Shared, private-on-first-use views . . . . . 159
Selected field properties . . . . . . . . . 135
Shared, desktop private-on-first-use views . . . 159
Hiding fields . . . . . . . . . . . . . 137
Private views . . . . . . . . . . . . 159
Hiding options . . . . . . . . . . . . 137
Creating a standard outline view . . . . . . . 159
To hide a field . . . . . . . . . . . . 137
Copying and deleting views . . . . . . . . 160
Creating a field in a layout region . . . . . . 138
To copy a view . . . . . . . . . . . . 160
To create a field in a layout region . . . . . 138
To delete a view . . . . . . . . . . . 160
To create a field label . . . . . . . . . . 139
Creating a default design for new views . . . . 160
To resize a field . . . . . . . . . . . 139
Designing folders . . . . . . . . . . . . 161
Adding HTML attributes to a field . . . . . . 139
Naming a view or folder . . . . . . . . . 161

vi Application Development with Domino Designer 7


Naming tips . . . . . . . . . . . . . 161 Usage Notes . . . . . . . . . . . . . 191
Aliases . . . . . . . . . . . . . . 161 To allow users to edit documents in a view . . 191
Hidden views . . . . . . . . . . . . 162 To allow users to create a new document from a
Shortcut keys . . . . . . . . . . . . 162 view . . . . . . . . . . . . . . . 191
Cascading views . . . . . . . . . . . 162 Coding notes . . . . . . . . . . . . 191
Customizing the style of the inbox folder . . . . 162 Allowing users to set colors in a view . . . . . 192
Using a previously created style . . . . . . 162 Setting the color value in the profile document 192
Selecting an inbox style . . . . . . . . . 163 Formulas that look for values in columns and
Selecting which documents display in a view. . . 163 views . . . . . . . . . . . . . . . . 192
Choosing the type of view selection . . . . . 163 Referring to views in @function formulas . . . 193
Simple Search . . . . . . . . . . . . 164 Referring to columns in formulas . . . . . . 193
Formula . . . . . . . . . . . . . . 164 Creating a calendar view . . . . . . . . . 193
Examples: Programming documents to display To create a calendar view . . . . . . . . 193
in a view . . . . . . . . . . . . . . 164 Formatting options for calendar views . . . . 194
Table of document selection conditions . . . . 164 Troubleshooting a calendar view . . . . . . 195
Description of document selection conditions 166 Setting styles for a calendar view . . . . . . 195
Creating columns in a view . . . . . . . . 167 Displaying views in Web applications . . . . . 196
Creating a shared column . . . . . . . . 167 Specifying how a view displays in a Web
Adding titles to columns . . . . . . . . 168 browser . . . . . . . . . . . . . . 196
Setting styles for columns . . . . . . . . 169 Creating an embedded view or embedded
Formatting date and time columns . . . . . 170 folder . . . . . . . . . . . . . . . 197
Displaying numbers in columns . . . . . . 171 Using HTML formatting for views and columns 200
Enabling a column for instant messaging . . . 171 Displaying a view as an applet in Web
Advanced options for columns . . . . . . 172 applications . . . . . . . . . . . . . 200
Adding programming to columns . . . . . 173 Allowing users to select view documents on the
Table of simple functions for columns . . . . 176 Web . . . . . . . . . . . . . . . 203
Displaying an icon in a column . . . . . . 178 Opening a view with a particular frameset on
Sorting documents in views . . . . . . . 179 the Web . . . . . . . . . . . . . . 203
Overriding alphabetical sorting with a hidden Hiding a view . . . . . . . . . . . . . 203
column . . . . . . . . . . . . . . 182 Hiding a view from Notes users . . . . . . 203
Using a column to switch to another view . . . 183 Hiding a view from Web users . . . . . . 203
Generating column totals, averages, and Showing a view only to users of older Notes
percents . . . . . . . . . . . . . . 183 releases . . . . . . . . . . . . . . 204
Setting styles for a standard view or folder . . . 183 Refreshing view indexes . . . . . . . . . . 204
Display options for views . . . . . . . . . 184 Refresh time options . . . . . . . . . . 204
Setting the view as the default . . . . . . 185 Refresh display options . . . . . . . . . 204
Using a view or folder as a template . . . . 185 Discard index options . . . . . . . . . 205
Collapsing the view to show only categories 185 When the view index is deleted . . . . . . 205
Organizing response documents in a hierarchy 185 Adding a trash folder to an application. . . . . 205
Adding a view name to the View menu . . . 185 Trash folders in the view applet . . . . . . 206
Allowing Notes users to customize a view . . 185 Adding a view for soft deletions . . . . . . . 206
Evaluating formulas when documents change 185 To turn on soft deletions for a database. . . . 206
Creating new documents at view level . . . . 185 Displaying and restoring soft-deleted documents 206
Opening to a particular row in the view . . . 185 DB2 query views . . . . . . . . . . . . 207
Displaying the last-used view . . . . . . . 186 Query views and federated data . . . . . . 207
Refreshing a view . . . . . . . . . . . 186 Using complex SQL queries in query views . . 208
Page breaks in a view . . . . . . . . . 186 Prerequisites for working with Notes databases
Adding categories to views . . . . . . . . . 186 that reside in DB2 . . . . . . . . . . . 208
To categorize a view . . . . . . . . . . 186 Creating a query view . . . . . . . . . 208
Generating category names . . . . . . . . 187 Managing query views . . . . . . . . . 210
Categorizing in the All by Category view . . . 188 @ functions for query views . . . . . . . 211
Indenting response documents . . . . . . 188
Formulas for response columns . . . . . . 189 Chapter 9. Designing navigation for
Identifying unread documents . . . . . . . . 190 an application . . . . . . . . . . . 213
Choosing a style for unread marks . . . . . 190
Outlines . . . . . . . . . . . . . . . 213
Choosing a color for unread marks . . . . . 190
Overview of creating a navigator . . . . . . 213
Disabling unread marks for modified
Creating an outline . . . . . . . . . . . 214
documents . . . . . . . . . . . . . 190
Designing for accessibility . . . . . . . . 214
Default views . . . . . . . . . . . . . 190
To create a new outline . . . . . . . . . 214
Allowing users to edit or create documents from a
To create a default outline . . . . . . . . 214
view . . . . . . . . . . . . . . . . 191
To add a new outline entry to an outline . . . 215

Contents vii
To reorder elements in an outline . . . . . . 215 Form events . . . . . . . . . . . . . 239
To create a hierarchy between elements . . . . 215 Examples. . . . . . . . . . . . . . 239
To delete an outline entry . . . . . . . . 215 Field events . . . . . . . . . . . . . 239
Embedding an outline . . . . . . . . . 216 Examples. . . . . . . . . . . . . . 240
Outline, outline entry, and embedded outline Click events . . . . . . . . . . . . . 240
properties . . . . . . . . . . . . . 216 Examples. . . . . . . . . . . . . . 240
Selected outline properties . . . . . . . . 217 Agent event . . . . . . . . . . . . . 240
Selected outline entry properties . . . . . . 217 Creating a form, subform, page, or view action . . 240
Selected embedded outline properties . . . . 218 To create an action with subaction . . . . . 241
Using the outline applet in Web applications 223 To create system actions . . . . . . . . . 242
Displaying the outline in a frameset . . . . . 224 Copying and deleting actions . . . . . . . 242
Navigators . . . . . . . . . . . . . . 224 Actions menu . . . . . . . . . . . . 242
Designing for accessibility . . . . . . . . 224 Calling an agent . . . . . . . . . . . 242
Navigator objects . . . . . . . . . . . 224 Action bar . . . . . . . . . . . . . . 242
Navigator actions . . . . . . . . . . . 225 Creating and inserting shared actions . . . . . 244
Creating a navigator . . . . . . . . . . . 225 To create a shared action . . . . . . . . 244
To edit a navigator . . . . . . . . . . 225 To create shared action notes . . . . . . . 245
Adding graphic objects to navigators . . . . 226 To delete a shared action note . . . . . . . 246
Adding and enhancing graphics in a navigator 226 To insert a shared action. . . . . . . . . 246
Adding text to and highlighting navigator To edit shared actions . . . . . . . . . 246
objects . . . . . . . . . . . . . . . 227 Creating a button . . . . . . . . . . . . 246
Adding hotspots . . . . . . . . . . . 227 Other button tasks. . . . . . . . . . . 247
Adding actions to navigators . . . . . . . 228 Creating a text pop-up . . . . . . . . . . 248
Displaying a navigator when users open a Other text pop-up tasks . . . . . . . . . 248
database . . . . . . . . . . . . . . 230 Example: Text pop-ups . . . . . . . . . 248
Hiding navigators . . . . . . . . . . . 230 Creating a formula pop-up . . . . . . . . . 248
Embedding navigators in a form, subform, Other formula pop-up tasks . . . . . . . 249
page, or document . . . . . . . . . . 231 Creating an action hotspot . . . . . . . . . 249
Overriding an embedded navigator with a Other action hotspot tasks . . . . . . . . 249
navigator template . . . . . . . . . . 231 Creating a program for an event . . . . . . . 250
Importing a navigator into a form, subform, Creating an agent . . . . . . . . . . . . 250
page, or document . . . . . . . . . . 232 Triggering an agent on an event . . . . . . 251
Testing navigators . . . . . . . . . . . 232 Triggering an agent on a schedule . . . . . 253
Creating an imagemap . . . . . . . . . . 233 Useful agent procedures . . . . . . . . . 254
To create an imagemap . . . . . . . . . 233 Examples of agents to run before Web users open
To move a hotspot. . . . . . . . . . . 233 or save documents . . . . . . . . . . . 256
To delete a hotspot from an imagemap . . . . 233 WebQueryOpen events . . . . . . . . . 256
To copy an imagemap . . . . . . . . . 233 WebQuerySave events . . . . . . . . . 256
To change the graphic for an imagemap . . . 234 Setting up agent security using the Security tab 256
Security for agents on servers and the Web . . . 257
Chapter 10. Adding automation to Who can create agents? . . . . . . . . . 258
applications . . . . . . . . . . . . 235 Who can run agents? . . . . . . . . . . 258
Private agents . . . . . . . . . . . . 258
Actions . . . . . . . . . . . . . . . 236
Shared agents . . . . . . . . . . . . 258
When to use actions . . . . . . . . . . 236
LotusScript/Java agents . . . . . . . . . 258
Examples of actions . . . . . . . . . . 236
Where can agents run? . . . . . . . . . 258
Notes on actions . . . . . . . . . . . 236
What operations can agents run? . . . . . . 259
Hotspots . . . . . . . . . . . . . . . 236
When are restrictions checked? . . . . . . 259
When to use hotspots . . . . . . . . . 237
Locally on Notes . . . . . . . . . . . 259
Examples of hotspots . . . . . . . . . . 237
On the server . . . . . . . . . . . . 259
Agents . . . . . . . . . . . . . . . 237
Foreground or background . . . . . . . . 260
When to use agents . . . . . . . . . . 237
From the Notes client or the Web . . . . . . 260
Notes on agents . . . . . . . . . . . 238
Security controls for agents that are called by
Events . . . . . . . . . . . . . . . . 238
agents . . . . . . . . . . . . . . . 260
When to use event programming . . . . . . 238
Troubleshooting agents . . . . . . . . . . 261
Examples of event programming . . . . . . 238
Testing agents . . . . . . . . . . . . . 261
Types of events . . . . . . . . . . . . 238
To use the Test menu command . . . . . . 261
Database events . . . . . . . . . . . 238
To use the LotusScript debugger . . . . . . 261
Examples: . . . . . . . . . . . . . 238
To create a test database . . . . . . . . . 262
View and folder events . . . . . . . . . 239
Profiling agents and Web services . . . . . . 262
Examples of view and folder events . . . . . 239
Viewing the agent log . . . . . . . . . . 263
Examples of calendar view events . . . . . 239

viii Application Development with Domino Designer 7


Notes server console commands . . . . . . . 263 Accessing database resources using a WebDAV
Tell amgr schedule . . . . . . . . . . 263 client . . . . . . . . . . . . . . . . 280
tell amgr status . . . . . . . . . . . . 264 Virtual collections . . . . . . . . . . . 280
tell amgr debug . . . . . . . . . . . 264 Accessing database elements . . . . . . . 281
Agent Manager debugging information. . . . . 264 Avoiding and resolving naming conflicts . . . 281
Debug_AMgr . . . . . . . . . . . . 265 Using WebDAV in a replicated environment . . . 282
Log_AgentManager . . . . . . . . . . 265
NotesLog Class . . . . . . . . . . . . . 265 Chapter 12. Connecting to enterprise
Agent Log limit . . . . . . . . . . . 266 data . . . . . . . . . . . . . . . 283
Simple actions for automation . . . . . . . . 266
Data Connection Resource (DCR) . . . . . . . 283
Copy to Database . . . . . . . . . . . 266
@DB commands . . . . . . . . . . . . 283
Copy to Folder . . . . . . . . . . . . 266
Domino Enterprise Connection Services (DECS) 283
Delete from Database . . . . . . . . . . 267
LotusScript and Java classes . . . . . . . . 284
Mark Document Read . . . . . . . . . 267
Domino Connectors . . . . . . . . . . . 284
Mark Document Unread . . . . . . . . . 267
Lotus Enterprise Integrator . . . . . . . . . 284
Modify Field . . . . . . . . . . . . 267
Table of connectivity solutions . . . . . . . . 284
Modify Fields by Form . . . . . . . . . 267
Overview of Data Connection Resources . . . . 285
Move to Folder . . . . . . . . . . . . 268
Overview of creating a DCR . . . . . . . 285
Remove from Folder . . . . . . . . . . 268
Establishing a data source resource for use with a
Reply to Sender . . . . . . . . . . . 268
DCR . . . . . . . . . . . . . . . . 286
Run Agent . . . . . . . . . . . . . 268
Creating a database connection resource . . . . 286
Send Document . . . . . . . . . . . 268
To create a DCR . . . . . . . . . . . 286
Send Mail Message . . . . . . . . . . 268
Specifying options for the data connection resource 287
Send Newsletter Summary . . . . . . . . 269
Maximum number of concurrent connections 287
@Function Formula . . . . . . . . . . 269
Block key field updates . . . . . . . . . 287
Using LotusScript for automation . . . . . . 269
Only update changed fields . . . . . . . 287
Working with HTML . . . . . . . . . . 269
Enable conflict detection . . . . . . . . . 287
Restricted LotusScript and Java agent operations 270
Space trimming . . . . . . . . . . . 287
Table of restricted backend class and method 270
Action on data mismatch . . . . . . . . 287
Table of restricted programming language
Action on missing record . . . . . . . . 287
operations . . . . . . . . . . . . . 271
Custom settings for specific applications . . . 288
Formulas for automation . . . . . . . . . 272
Enabling connections to external databases . . . 288
Using @command formulas with actions and
Using a data connection resource on a form . . . 288
hotspots . . . . . . . . . . . . . . 272
To specify a default data connection for a form 288
Security features that affect automation
To create fields for connecting with external
formulas . . . . . . . . . . . . . . 272
data . . . . . . . . . . . . . . . 289
JavaScript for automation . . . . . . . . . 273
Importing data from an external database into an
Table of supported JavaScript objects for automated
application . . . . . . . . . . . . . . 289
components . . . . . . . . . . . . . . 273
Using ODBC to access relational databases . . . 290
Actions and agents names . . . . . . . . . 274
Files required to use ODBC. . . . . . . . 290
Naming tips . . . . . . . . . . . . . 274
Registering data sources for ODBC . . . . . . 290
Naming techniques . . . . . . . . . . 274
To register a data source for ODBC in Windows 291
Aliases . . . . . . . . . . . . . . 274
Setting up a view for ODBC access . . . . . . 291
Shortcut keys . . . . . . . . . . . . 275
Writing formulas and scripts to access relational
Hiding automated components . . . . . . . 275
databases . . . . . . . . . . . . . . . 291
The LotusScript Data Object (LS:DO) . . . . 292
Chapter 11. Developing applications
using third-party tools and WebDAV . 277 Chapter 13. Including Java applets in
Customizing the Designer Tools menu . . . . . 277 applications . . . . . . . . . . . . 293
To add a tool . . . . . . . . . . . . 277
Requirements and restrictions for Java applets . . 293
Organizing tools on the Tools menu . . . . . . 278
Overview of adding a Java applet to an application 293
To add a submenu for tools . . . . . . . 278
Enabling Java applets. . . . . . . . . . . 294
To move a tool to another design context . . . 278
Importing an applet . . . . . . . . . . . 294
To copy, paste, or delete a tool: . . . . . . 278
Getting the main class name . . . . . . . 294
To edit a tool . . . . . . . . . . . . 278
Selecting related files . . . . . . . . . . 294
Editing and managing database resources using a
Importing applets packaged as CAB or ZIP files 295
WebDAV client . . . . . . . . . . . . . 278
Linking to an applet on the Web . . . . . . . 295
Setting up WebDAV . . . . . . . . . . 279
Setting applet parameters . . . . . . . . . 295
Enabling design locking . . . . . . . . . 279
To set individual applet parameters . . . . . 296
Notes about working with WebDAV . . . . . 279
To set all applet parameters . . . . . . . 296
Limitations . . . . . . . . . . . . . 280

Contents ix
Tips . . . . . . . . . . . . . . . 296 URL extension mapping . . . . . . . . 312
Specifying applet parameters, attributes, and Load on startup . . . . . . . . . . . 312
properties . . . . . . . . . . . . . . 296 Example properties file . . . . . . . . . 312
Setting HTML attributes . . . . . . . . . . 297
Setting Alternate HTML attributes . . . . . . 297 Chapter 15. Including XML in Designer
Setting properties . . . . . . . . . . . . 297 applications . . . . . . . . . . . . 313
To set applet properties . . . . . . . . . 297
What is DXL? . . . . . . . . . . . . . 314
To hide an applet under certain conditions . . 298
Domino applications and XML . . . . . . . 315
To hide an applet based on the browser
Applications enhanced with XML . . . . . 315
accessing it . . . . . . . . . . . . . 298
Ways to include XML in a Designer application 315
Setting up shared applet resources . . . . . . 298
XML terminology . . . . . . . . . . . . 316
To create a shared applet resource . . . . . 298
Putting XML in a form or page . . . . . . . 317
To use a shared applet resource . . . . . . 299
Defining data on a form with XML elements 317
Stopping, selecting, and restarting applets . . . . 299
To create documents in XML format . . . . . 318
To stop an applet . . . . . . . . . . . 299
Formatting XML data with stylesheets . . . . 318
To select an applet . . . . . . . . . . . 299
Using a view to generate XML . . . . . . . 319
To restart an applet . . . . . . . . . . 299
Mapping XML tags to a view . . . . . . . 319
Copying and deleting applets . . . . . . . . 299
Example . . . . . . . . . . . . . . 320
To delete an applet and its related files . . . . 300
To map XML to a view . . . . . . . . . 320
To copy an applet . . . . . . . . . . . 300
Embedding a view in a page . . . . . . . 321
Refreshing and exporting applet files . . . . . 300
Using an agent to generate XML . . . . . . . 321
To refresh applet files. . . . . . . . . . 300
Example: XML Agent . . . . . . . . . . 322
To export files . . . . . . . . . . . . 300
Using a Java servlet to generate XML . . . . . 323
Setting security for applets . . . . . . . . . 300
Examples of XML servlet applications . . . . 323
To set security for applets in Notes . . . . . 300
Creating and using a servlet . . . . . . . 324
To set security for applets in Web applications 301
Including XML in a servlet . . . . . . . . 324
To extend the AppletBase class . . . . . . 301
Viewing the XML in an application with DXL
Saving applet data . . . . . . . . . . . 302
utilities . . . . . . . . . . . . . . . 324
Considerations . . . . . . . . . . . . 302
To view the XML for a design element . . . . 324
Externalization . . . . . . . . . . . . 302
To export the XML for one or more design
To set up externalization . . . . . . . . 303
elements to a text file . . . . . . . . . . 324
Example HTML code . . . . . . . . . . 303
To transform the XML for one or more design
Serialization . . . . . . . . . . . . . 303
elements using an XSL . . . . . . . . . 325
To set serialization . . . . . . . . . . . 304
Example of HTML code . . . . . . . . . 304
Tips and troubleshooting for Java applets . . . . 304 Chapter 16. Including OLE objects in
Troubleshooting an applet that is not running 304 applications . . . . . . . . . . . . 327
Accessing resource files . . . . . . . . . 304 Linking and embedding objects in forms . . . . 327
Specifying a full URL. . . . . . . . . . 305 OLE and LotusScript . . . . . . . . . . 328
Using getDocumentBase . . . . . . . . . 305 To link an object in a form . . . . . . . . 328
Using getCodeBase . . . . . . . . . . 306 To embed an object in a form . . . . . . . 328
Modifying parameter values to locate resource Adding OLE custom controls to a form . . . . . 328
files . . . . . . . . . . . . . . . 306 To create an OLE custom control object . . . . 328
Troubleshooting tips for OLE and Active X objects 329
Chapter 14. Including Java servlets in Modifying a form to size an embedded object . . 330
To edit the OLE object using the properties box 330
Web applications . . . . . . . . . . 307
To edit the OLE object using the properties in
Comparing agents, servlets, and CGI programs . . 307
the programmer’s pane . . . . . . . . . 330
What language can the program be written in? 308
Modifying a form so that it sizes an OLE custom
Where is the program stored? . . . . . . . 308
control . . . . . . . . . . . . . . . 330
How is the program invoked by a Web user? 308
To edit the OLE custom control using the
When is the program loaded and unloaded by
properties box . . . . . . . . . . . . 330
the server? . . . . . . . . . . . . . 308
To edit the OLE custom control in the
How can the program interact with Domino? 308
Programmer’s pane . . . . . . . . . . 330
What security is available for the program? 308
Expansion properties of OLE custom controls 331
Running servlets in Domino . . . . . . . . 309
Modifying a form to run a custom control in Read
Writing the servlet . . . . . . . . . . 309
mode . . . . . . . . . . . . . . . . 331
Enabling servlet support in Domino . . . . 309
Updating objects by document . . . . . . . 331
Loading servlet classes with the JVM loader 310
To modify properties using the properties box 331
Setting properties for servlets . . . . . . . 311
To modify properties using the properties sheet
Servlet aliases . . . . . . . . . . . . 311
in the Programmer’s pane . . . . . . . . 332
Initialization arguments . . . . . . . . 311

x Application Development with Domino Designer 7


Launching objects automatically . . . . . . . 332 Chapter 18. Enabling an application
Launch an object automatically . . . . . . 332 for Domino Off-Line Services . . . . 349
Launch a new object automatically . . . . . 332 Overview of DOLS developer tasks . . . . . . 349
Launch an object in-place or out-of-place . . . 332 Copying DOLS design elements into the main
Define the conditions under which objects are database . . . . . . . . . . . . . . . 349
launched . . . . . . . . . . . . . . 332 Customizing how users install the DOLS
Use the form open in a modal dialog box to subscription . . . . . . . . . . . . . . 350
create documents . . . . . . . . . . . 332 Using the Web Control . . . . . . . . . 350
Hide the Notes document . . . . . . . . 332 Using an icon . . . . . . . . . . . . 351
Hide the original embedded object in Configuring the DOLS subscription . . . . . . 351
documents . . . . . . . . . . . . . 333 To edit the configuration document . . . . . 352
Designing forms that launch objects Creating multiple database DOLS subscriptions 357
automatically . . . . . . . . . . . . 333 Optional tasks for DOLS developers . . . . . . 358
Launching an object ″in-place″ or ″out-of-place″ 334 Creating custom file sets for a DOLS
Specifying the event that causes an object to subscription . . . . . . . . . . . . . 358
autolaunch . . . . . . . . . . . . . 334 Customizing fields and design elements in a
Designing a form that launches an object from DOLS subscription . . . . . . . . . . 359
modal dialog boxes . . . . . . . . . . 335 Adding a directory catalog to a DOLS
Designing a form to hide the Notes document . . 335 subscription . . . . . . . . . . . . . 362
When you can hide the Notes document . . . 335 Adding time zones to a DOLS subscription . . 363
Mixing Hide/Show options . . . . . . . 335 Setting a sort order for a DOLS subscription . . 363
To hide a Notes document . . . . . . . . 336
Example . . . . . . . . . . . . . . 336
Hiding an embedded object in a document . . . 337
Chapter 19. Security in an application 365
Publishing actions . . . . . . . . . . . . 337 The database access control list . . . . . . . 365
When an action executes . . . . . . . . 337 Setting up a database ACL . . . . . . . . 365
″Bring document window to front″ property 337 Access levels in the ACL . . . . . . . . 366
To publish an action . . . . . . . . . . 338 Access level privileges in the ACL . . . . . 368
Examples . . . . . . . . . . . . . . 338 Roles in the ACL . . . . . . . . . . . 370
Exchanging field data . . . . . . . . . . 338 Editing the database ACL . . . . . . . . 372
One-way fields . . . . . . . . . . . . 338 Default ACL entries . . . . . . . . . . 372
Two-way fields . . . . . . . . . . . . 339 Acceptable entries in the ACL . . . . . . . 373
User-defined fields . . . . . . . . . . 339 User types in the ACL . . . . . . . . . 378
Preparing a form to exchange data . . . . . . 339 Enforcing a consistent access control list . . . 379
Table of one-way and two-way field exchange 339 Displaying the ACL history. . . . . . . . 380
To enable field exchange . . . . . . . . 339 To display a name’s effective access . . . . . 380
To set up field exchange . . . . . . . . . 340 Security overview for Web applications . . . . 380
Example of exchanging data for an expense Application design element security . . . . . . 383
form . . . . . . . . . . . . . . . 340 Controlling access to a database during design 383
Restricting who can read or edit documents . . 384
Using a Readers field to restrict access to
Chapter 17. Creating a workflow specific documents . . . . . . . . . . 384
application . . . . . . . . . . . . 343 Using an Authors field to restrict who can edit
Examples of workflow applications . . . . . . 343 specific documents . . . . . . . . . . 384
Planning workflow . . . . . . . . . . . 343 To create Readers and Authors fields . . . . 385
Central shared databases . . . . . . . . 343 Tracking who edits a document . . . . . . 386
Individual mail databases . . . . . . . . 344 Updating Readers and Authors fields . . . . 386
Setting up automatic mailing . . . . . . . . 344 Setting up the Administration Process for
Sending links to documents . . . . . . . 344 databases . . . . . . . . . . . . . . 387
Sending documents . . . . . . . . . . 344 Creating controlled-access sections of forms . . 387
Enabling users to view documents . . . . . 345 Examples of access-controlled sections . . . . 388
Forwarding documents in a mail memo . . . 345 Limiting Editor access to sections of forms . . 388
Sending replies to a mail memo . . . . . . 345 Creating read access lists to limit view and
Mailing features and Web applications . . . . . 345 folder access . . . . . . . . . . . . . 389
Displaying the Mail Send dialog box . . . . . 345 Creating write access lists to limit folder access 390
Creating a database that receives mailings . . . . 345 Access-controlled forms and documents . . . 390
Example of using an agent that sends automatic Creating public access pages, forms, subforms,
replies . . . . . . . . . . . . . . . . 346 outlines, views, agents, and style sheets . . . 391
Example of using an agent that mails action item Notes and Domino encryption . . . . . . . . 392
notices . . . . . . . . . . . . . . . 346 Database encryption . . . . . . . . . . 393
Example of using an agent that sends To encrypt a database . . . . . . . . . 393
announcements . . . . . . . . . . . . . 347

Contents xi
Encrypting documents and fields . . . . . . 394 To remove field data from all documents . . . 416
Procedural overview: encrypting documents . . 395 To rename a field . . . . . . . . . . . 416
Enabling encryption for a field . . . . . . 395 To reassign documents to another form . . . . 416
Creating secret encryption keys . . . . . . 396 To remove the stored form from documents . . 416
Distributing secret encryption keys . . . . . 396 To specify a form to display documents . . . 417
Merging secret encryption keys . . . . . . 397 To recover additional space . . . . . . . . 417
To create a field that maintains a list of secret Changing database and design properties . . . . 417
encryption keys . . . . . . . . . . . 398 To change a database’s properties . . . . . 417
Managing encrypted information . . . . . . 398 To change a design element’s properties . . . 417
To encrypt all documents automatically . . . 399 Setting database launch properties . . . . . . 418
Using electronic signatures in Notes applications 400 To set the database launch property . . . . . 418
Attaching signatures to documents . . . . . 401 If you choose to launch a doclink. . . . . . 418
To launch a Page from the Notes client . . . . 419
Chapter 20. Completing an application Displaying a document preview automatically 419
and managing design changes . . . . 403 Templates . . . . . . . . . . . . . . 419
To convert a database to a template . . . . . 419
Creating a database icon for a Notes application 403
Naming conventions . . . . . . . . . . 420
To paste an icon into a database . . . . . . 403
Creating templates . . . . . . . . . . 420
To create a new icon . . . . . . . . . . 403
Creating a design library template . . . . . 422
Providing online Help for an application . . . . 404
Linking a database to a template . . . . . . 423
Creating ″Using Database″ and ″About Database″
Linking individual design elements to a
documents . . . . . . . . . . . . . . 404
template . . . . . . . . . . . . . . 424
The ″About Database″ document . . . . . . 404
Synchronizing databases with master templates 424
The ″Using Database″ document . . . . . . 404
Making and distributing design changes . . . . 425
To create a document . . . . . . . . . . 405
Refreshing a design . . . . . . . . . . . 426
To automatically display the ″About Database″
Automatically refreshing a design . . . . . 426
document . . . . . . . . . . . . . 405
Manually refreshing a design . . . . . . . 427
Creating context-sensitive Help for an application 405
Components that are not refreshed . . . . . 427
Writing Help for fields . . . . . . . . . . 406
Components that are refreshed . . . . . . 427
Tips for writing Help for fields . . . . . . 406
Refreshing a design manually . . . . . . . 427
To write field Help . . . . . . . . . . 406
Replacing a design . . . . . . . . . . . 428
To write pop-up text for a field . . . . . . 406
Components that are not replaced during
To write a field hint . . . . . . . . . . 407
Replace Design . . . . . . . . . . . . 428
Examples . . . . . . . . . . . . . . 407
Components that are replaced during Replace
Creating and displaying more detailed application
Design . . . . . . . . . . . . . . 428
Help . . . . . . . . . . . . . . . . 407
To replace the design of a database . . . . . 429
To create a Help form . . . . . . . . . 407
Design changes and replication . . . . . . . 429
Specifying a home page in the Web site document 407
Templates and replication . . . . . . . . 429
Restricting design changes . . . . . . . . . 408
Preventing design changes . . . . . . . . . 429
Checking the application design before release . . 408
To protect individual design elements from
Checking form design . . . . . . . . . . 409
being replaced or refreshed . . . . . . . . 429
Checking field design . . . . . . . . . . 409
To unlink individual design elements from a
Checking view design . . . . . . . . . . 410
template . . . . . . . . . . . . . . 430
Checking columns . . . . . . . . . . . 411
To unlink a database from a template . . . . 430
Making a design copy of a completed application 411
Modifying multiple design elements . . . . . . 430
Pilot testing an application . . . . . . . . . 412
Hiding the design of a database . . . . . . . 431
To pilot test an application . . . . . . . . 412
To hide the design of a database . . . . . . 431
Renaming a database . . . . . . . . . . . 413
Building in access to agents before hiding the
Renaming design elements . . . . . . . . . 413
design . . . . . . . . . . . . . . . 431
Design synopsis . . . . . . . . . . . . 413
Hiding design elements . . . . . . . . . . 432
To create a design synopsis . . . . . . . . 413
″Hide design element from″ . . . . . . . 432
Updating documents after redesigning a form . . 414
″Do not show this design element in menus of
Form changes that don’t require updates to
Notes R4 or later clients″ . . . . . . . . 432
existing documents . . . . . . . . . . 414
To hide design elements . . . . . . . . . 432
Form changes that require updates to existing
Locking a design element . . . . . . . . . 432
documents . . . . . . . . . . . . . 415
To enable design element locking . . . . . . 433
Checking field values in a document . . . . . 415
To lock a design element . . . . . . . . 433
To check field values in a document: . . . . 415
To unlock a design element . . . . . . . . 433
Using agents to update documents affected by
To disable design element locking . . . . . 433
form changes . . . . . . . . . . . . . 415
To edit and resave documents . . . . . . . 416
To add a field . . . . . . . . . . . . 416 Chapter 21. Deploying an application 435

xii Application Development with Domino Designer 7


Rolling out a database . . . . . . . . . . 435 Managing database activity recording in
Mandatory tasks . . . . . . . . . . . 435 databases . . . . . . . . . . . . . . 463
Optional tasks . . . . . . . . . . . . 436 Updating database indexes and views . . . . 463
Copying a new database to a server . . . . . . 437 Notifying users of a moved database . . . . . 464
To copy a new database to a server . . . . . 437 Adding a button to open a database . . . . . 464
Setting up replication for an application . . . . 438 Troubleshooting database performance . . . . . 464
Creating one replica manually . . . . . . . . 438 Users cannot access the database . . . . . . 464
Replication settings . . . . . . . . . . . 439 Users experience a delay when accessing the
Limiting the contents of a replica . . . . . . 440 database . . . . . . . . . . . . . . 465
Assigning miscellaneous replication settings . . 442 Using Find Note to analyze a document
Limiting what a replica sends . . . . . . . 443 reported in the log file . . . . . . . . . 466
Specifying replication settings . . . . . . . 443 Troubleshooting replication problems . . . . . 466
Examples of specifying replication settings for A database replica does not contain all the
multiple replicas . . . . . . . . . . . 444 documents it should . . . . . . . . . . 466
Disabling and enabling replication of a database 446 A database replica is not receiving design
To disable replication of one database . . . . 446 changes . . . . . . . . . . . . . . 467
To disable replication of multiple databases . . 446 Changes to the database title do not replicate 467
Forcing a server database to replicate . . . . . 447 Database replicas are different sizes . . . . . 467
To force replication from the server console . . 447 The database stops replicating . . . . . . . 468
To force replication from the database . . . . 447 The database replica has not received ACL
changes . . . . . . . . . . . . . . 468
Chapter 22. Optimizing and The new replica contains the ACL of the source
troubleshooting databases . . . . . 449 server but you did not copy the ACL . . . . 468
You see the message ″Database is not fully
Properties that improve database performance . . 449
initialized yet″ . . . . . . . . . . . . 468
Display images after documents . . . . . . 449
Deletions are not replicating . . . . . . . 469
Prevent the use of stored forms . . . . . . 449
Unexpected deletions occur in a replica . . . 469
Don’t maintain unread marks . . . . . . . 449
Deleted documents reappear . . . . . . . 469
Associate document tables with forms for view
updates . . . . . . . . . . . . . . 450
Prevent overwriting of deleted data . . . . . 450 Chapter 23. DB2 Access views . . . . 471
Don’t maintain ″Accessed (In this file)″ Prerequisites for working with Notes databases
document property . . . . . . . . . . 450 that reside in DB2 . . . . . . . . . . . . 472
Disable specialized response hierarchy DAV security . . . . . . . . . . . . . 472
information . . . . . . . . . . . . . 451 Creating a DAV . . . . . . . . . . . . 473
Disable transaction logging . . . . . . . . 451 Viewing the status of your DAV . . . . . . 475
Prevent headline monitoring . . . . . . . 451 Managing DAVs . . . . . . . . . . . . 475
Allow more fields in a database . . . . . . 452 In Designer . . . . . . . . . . . . . 476
Use LZ1 compression for attachments . . . . 452 In DB2 . . . . . . . . . . . . . . 476
Limit the size of $UpdatedBy fields . . . . . 452 Troubleshooting DAVs . . . . . . . . . . 476
Limit the size of $Revisions fields . . . . . 452 ACLs needed for DAVs . . . . . . . . . 476
Specify expiration time for soft deletions . . . 452 Errors using the Select statement . . . . . . 476
To set database properties that optimize database Exporting TIMEDATES to DAVs . . . . . . 477
performance . . . . . . . . . . . . . . 453 Inserting date ranges in a DAV . . . . . . 477
Controlling database size . . . . . . . . . 454 Unknown host error . . . . . . . . . . 477
Monitoring database size . . . . . . . . 454 Updatable cursors do not work . . . . . . 477
Compacting databases . . . . . . . . . 454 Using GMT TimeDates with Query Views based
Document archiving tool . . . . . . . . . 456 on DAVs . . . . . . . . . . . . . . 477
To enable database archiving . . . . . . . 456
Archive Settings . . . . . . . . . . . 456 Appendix A. Domino
Viewing a document Archiving Log . . . . . 457 Designer templates . . . . . . . . . 479
Using an agent to delete and archive documents 457 Table of Domino Designer templates . . . . . 479
Monitoring replication of a database . . . . . . 458
The database replication history . . . . . . 458
Appendix B. Importing to
Viewing replication events in the log file . . . 459
Replication or save conflicts . . . . . . . 460 and exporting from views . . . . . . 481
Consolidating replication or save conflicts . . . 460 File formats you can export and import . . . . 481
Monitoring database activity . . . . . . . . 461 Importing options . . . . . . . . . . . . 481
How the Statlog task generates activity statistics 461 Formatting options . . . . . . . . . . 481
Viewing database activity statistics generated by Including additional fields for imported
the Statlog task . . . . . . . . . . . . 462 documents . . . . . . . . . . . . . 481
Character translation file . . . . . . . . 482

Contents xiii
Importing worksheets . . . . . . . . . . 482 Domino formatting features that are not supported
To import worksheet data into a view . . . . 482 on the Web . . . . . . . . . . . . . . 498
Importing tabular text . . . . . . . . . . 482 Domino frame properties that are not supported on
Viewing imported text . . . . . . . . . 483 the Web . . . . . . . . . . . . . . . 498
To import tabular text into a view . . . . . 483 Domino horizontal rule properties that are not
Importing structured text files . . . . . . . . 483 supported on the Web . . . . . . . . . . 499
To import structured text into a view . . . . 483 Domino hotspot properties that are not supported
Creating a column descriptor (COL) file . . . . 484 on the Web . . . . . . . . . . . . . . 499
Using a column descriptor file (COL ) to map a Domino navigator properties that are not
source file to a Notes view . . . . . . . . . 484 supported on the Web . . . . . . . . . . 499
Mapping a column to a field in a view . . . . 484 Domino table properties that are not supported on
Specifying the data type of a column . . . . 484 the Web . . . . . . . . . . . . . . . 499
Using formulas . . . . . . . . . . . . 485 Domino text styles that are not supported on the
Writing a COL file for a worksheet . . . . . . 485 Web . . . . . . . . . . . . . . . . 500
WKSCOL . . . . . . . . . . . . . . 485 Domino view and folder properties that are not
RANGE . . . . . . . . . . . . . . 485 supported on the Web . . . . . . . . . . 500
Writing a COL file for a tabular text file . . . . 486 Features that are not supported by the Domino
Specifying the delimiter of a column . . . . 486 view applet . . . . . . . . . . . . . . 501
Specifying the start, end, and width of a
fixed-width column . . . . . . . . . . 486 Appendix E. URL
Specifying the header, footer, and lines per page 486 commands for Web applications . . . 503
Writing formulas for COL files . . . . . . . 487
Domino URL Commands . . . . . . . . . 503
Example . . . . . . . . . . . . . . 487
The Domino URL command syntax . . . . . 503
Exporting views . . . . . . . . . . . . 487
Syntax Guidelines . . . . . . . . . . . 503
Exporting to an ASCII file with comma
URL commands for opening servers, databases,
separated values . . . . . . . . . . . 487
and views . . . . . . . . . . . . . . 505
Notes on exporting as a CSV file . . . . . . 487
Redirect . . . . . . . . . . . . . . 505
Exporting to a worksheet . . . . . . . . 487
Syntax . . . . . . . . . . . . . . . 505
Exporting to a tabular text file . . . . . . . 488
Example . . . . . . . . . . . . . . 505
Exporting to a structured text file. . . . . . 488
OpenDatabase . . . . . . . . . . . . 505
To export a view . . . . . . . . . . . 488
Syntax . . . . . . . . . . . . . . . 505
Delimiter and word wrap settings . . . . . 488
Examples . . . . . . . . . . . . . . 506
OpenView . . . . . . . . . . . . . 506
Appendix C. Developing Syntax . . . . . . . . . . . . . . . 506
applications using MAPI. . . . . . . 491 Examples . . . . . . . . . . . . . . 506
The Address Book provider . . . . . . . . 491 Optional arguments for OpenView . . . . . 506
The Message Store provider . . . . . . . . 491 Examples . . . . . . . . . . . . . . 507
The Message Transport provider . . . . . . . 492 ReadViewEntries . . . . . . . . . . . 507
MAPI recipient types . . . . . . . . . . . 492 Syntax . . . . . . . . . . . . . . . 507
Platforms and requirements for MAPI . . . . . 492 Examples . . . . . . . . . . . . . . 507
Windows 98 . . . . . . . . . . . . . 492 Optional arguments for ReadViewEntries . . . 507
Windows NT 3.51 . . . . . . . . . . . 492 Examples . . . . . . . . . . . . . . 509
Windows NT 4.0 . . . . . . . . . . . 492 OpenAbout . . . . . . . . . . . . . 509
Windows 2000 . . . . . . . . . . . . 492 Syntax . . . . . . . . . . . . . . . 509
Mail . . . . . . . . . . . . . . . 492 Example . . . . . . . . . . . . . . 509
Address Book template . . . . . . . . . 493 OpenHelp . . . . . . . . . . . . . 509
MAPI classes and methods . . . . . . . . . 493 Syntax . . . . . . . . . . . . . . . 510
Example . . . . . . . . . . . . . . 510
Appendix D. Features to OpenIcon . . . . . . . . . . . . . . 510
avoid using in Web applications . . . 495 Syntax . . . . . . . . . . . . . . . 510
Example . . . . . . . . . . . . . . 510
Domino @functions that are not supported on the
URL commands for opening framesets . . . . . 510
Web . . . . . . . . . . . . . . . . 495
OpenFrameset . . . . . . . . . . . . 510
Domino actions and agent properties that are not
Syntax . . . . . . . . . . . . . . . 510
supported on the Web . . . . . . . . . . 496
Examples . . . . . . . . . . . . . . 510
Domino calendar features that are not supported
URL commands for opening agents, forms, and
on the Web . . . . . . . . . . . . . . 496
navigators . . . . . . . . . . . . . . 510
Domino field properties that are not supported on
OpenAgent . . . . . . . . . . . . . 510
the Web . . . . . . . . . . . . . . . 497
Syntax . . . . . . . . . . . . . . . 510
Domino form properties that are not supported on
Examples . . . . . . . . . . . . . . 510
the Web . . . . . . . . . . . . . . . 497
OpenForm . . . . . . . . . . . . . 511

xiv Application Development with Domino Designer 7


Syntax . . . . . . . . . . . . . . . 511 Syntax . . . . . . . . . . . . . . . 517
Examples . . . . . . . . . . . . . . 511 Optional argument forOpenElement . . . . 517
Optional argument forOpenForm . . . . . 511 Using OpenElement with OLE Objects . . . . 518
Syntax . . . . . . . . . . . . . . . 511 Syntax . . . . . . . . . . . . . . . 518
Example . . . . . . . . . . . . . . 511 URL commands for searching for text . . . . . 518
OpenNavigator . . . . . . . . . . . . 511 SearchDomain . . . . . . . . . . . . 518
Syntax . . . . . . . . . . . . . . . 511 Syntax . . . . . . . . . . . . . . . 518
Examples . . . . . . . . . . . . . . 511 Example . . . . . . . . . . . . . . 518
ReadForm . . . . . . . . . . . . . 511 Redirect . . . . . . . . . . . . . . 518
Syntax . . . . . . . . . . . . . . . 511 SearchSite . . . . . . . . . . . . . 518
Examples . . . . . . . . . . . . . . 512 Syntax . . . . . . . . . . . . . . . 519
URL commands for opening resources . . . . . 512 Example . . . . . . . . . . . . . . 519
OpenImageResource . . . . . . . . . . 512 SearchView . . . . . . . . . . . . . 519
Syntax . . . . . . . . . . . . . . . 512 Syntax . . . . . . . . . . . . . . . 519
Examples . . . . . . . . . . . . . . 512 Example . . . . . . . . . . . . . . 519
OpenFileResource . . . . . . . . . . . 512 Optional arguments for SearchSite, SearchView,
Syntax . . . . . . . . . . . . . . . 512 and SearchDomain . . . . . . . . . . 519
Examples . . . . . . . . . . . . . . 512 Examples . . . . . . . . . . . . . . 520
URL commands for creating, deleting, editing, URL search syntax and customized results . . 520
opening, and saving documents . . . . . . . 512 Start and Count parameters . . . . . . . 521
CreateDocument . . . . . . . . . . . 512 Syntax . . . . . . . . . . . . . . . 521
Syntax . . . . . . . . . . . . . . . 513 Examples . . . . . . . . . . . . . . 521
Examples . . . . . . . . . . . . . . 513 Using Next and Previous buttons or hotspots with
DeleteDocument . . . . . . . . . . . 513 Start and Count parameters . . . . . . . . 521
Syntax . . . . . . . . . . . . . . . 513 Example of a formula for a Next button or
Example . . . . . . . . . . . . . . 513 hotspot . . . . . . . . . . . . . . 521
EditDocument . . . . . . . . . . . . 513 Example of a formula for a Previous button or
Syntax . . . . . . . . . . . . . . . 513 hotspot . . . . . . . . . . . . . . 521
Example . . . . . . . . . . . . . . 513 URL commands for required authentication . . . 522
OpenDocument. . . . . . . . . . . . 513 Login argument . . . . . . . . . . . 522
Syntax . . . . . . . . . . . . . . . 513 Syntax . . . . . . . . . . . . . . . 522
Examples . . . . . . . . . . . . . . 514 Examples . . . . . . . . . . . . . . 522
SaveDocument . . . . . . . . . . . . 514 Logout command . . . . . . . . . . . 522
Syntax . . . . . . . . . . . . . . . 514 Syntax . . . . . . . . . . . . . . . 522
Example . . . . . . . . . . . . . . 514 Examples . . . . . . . . . . . . . . 522
URL commands for opening documents by key 514 URL commands for processing SSL certificates . . 522
Using Domino URLs to access a document . . 514 OpenForm with SpecialAction argument . . . 522
Syntax . . . . . . . . . . . . . . . 514 Syntax . . . . . . . . . . . . . . . 522
Examples . . . . . . . . . . . . . . 515 Examples . . . . . . . . . . . . . . 523
Using @commands to link to a document . . . 515 Creating an SSL User Certificate . . . . . . 523
Using Domino URLs to access attachments . . 515 Syntax . . . . . . . . . . . . . . . 523
URL commands for opening pages . . . . . . 515 Example . . . . . . . . . . . . . . 523
OpenPage . . . . . . . . . . . . . 515 Optional and required fields . . . . . . . 523
Syntax . . . . . . . . . . . . . . . 515 Creating an SSL Server Certificate Request . . 524
Examples . . . . . . . . . . . . . . 515 Syntax . . . . . . . . . . . . . . . 524
Optional arguments for OpenPage and Example . . . . . . . . . . . . . . 524
OpenDocument. . . . . . . . . . . . 515 Optional and required fields . . . . . . . 524
Syntax . . . . . . . . . . . . . . . 516 URL commands for setting user preferences in Web
Examples . . . . . . . . . . . . . . 516 applications . . . . . . . . . . . . . . 524
Syntax . . . . . . . . . . . . . . . 516 OpenPreferences . . . . . . . . . . . 525
Examples . . . . . . . . . . . . . . 516 Syntax . . . . . . . . . . . . . . . 525
Arguments . . . . . . . . . . . . . 516 Examples . . . . . . . . . . . . . . 525
Syntax . . . . . . . . . . . . . . . 516 Optional arguments for OpenPreferences . . . 525
Examples . . . . . . . . . . . . . . 517 Managing multilingual input in a single database 527
URL commands for opening attachments, image Syntax . . . . . . . . . . . . . . . 527
files, and OLE objects . . . . . . . . . . 517 Usage . . . . . . . . . . . . . . . 527
OpenElement . . . . . . . . . . . . 517 Example . . . . . . . . . . . . . . 527
Using OpenElement with attachments . . . . 517 Perl Scripts . . . . . . . . . . . . . . 528
Syntax . . . . . . . . . . . . . . . 517 Common Gateway Interface (CGI) programs . . . 528
Example . . . . . . . . . . . . . . 517 Running a CGI program . . . . . . . . . 528
Using OpenElement with image files . . . . 517 CGI variables . . . . . . . . . . . . 528

Contents xv
Creating a field with the name of the CGI Keyboard shortcuts for databases . . . . . . . 533
variable . . . . . . . . . . . . . . 528 Keyboard shortcuts for dialog boxes . . . . . . 533
Table of CGI variable names . . . . . . . 529 Keyboard shortcuts for properties boxes . . . . 534
Keyboard shortcuts for documents . . . . . . 534
Appendix F. Accessibility Keyboard shortcuts to select and move text in a
and Keyboard Shortcuts . . . . . . 531 document . . . . . . . . . . . . . . 535
Keyboard shortcuts to move the cursor in a
Accessibility and keyboard shortcuts . . . . . 531
document . . . . . . . . . . . . . . 536
Enabling and using extended accelerator keys . . 531
Keyboard shortcuts to change text and paragraph
To enable extended accelerators for the
properties in a document . . . . . . . . . 536
Bookmark bar . . . . . . . . . . . . 531
Keyboard shortcuts to navigate within views,
To use extended accelerators in the Bookmark
folders, and panes . . . . . . . . . . . . 537
bar . . . . . . . . . . . . . . . . 531
Keyboard shortcuts when working in views . . . 537
To enable keyboard navigation of window tabs 531
To use extended accelerators in window tabs 531
Keyboard shortcuts . . . . . . . . . . . 532 Index . . . . . . . . . . . . . . . 539
Keyboard shortcuts for the Designer interface and
windows . . . . . . . . . . . . . . . 532

xvi Application Development with Domino Designer 7


Chapter 1. Introduction to Domino Designer
Welcome to IBM® Lotus® Domino Designer®. Domino Designer is an integrated application development
environment that lets developers and Web site designers create, manage, and deploy secure, interactive
applications.

This overview introduces some of the features you will use to create applications.

The ″What’s new in this release″ chapter provides quick links to topics defining the new features in Lotus
Domino Designer Release 7.

Overview -- applications and databases


A major new enhancement for Domino Designer Release 6.5 is the integration with Lotus Instant
Messaging.

One major focus of Domino Designer Release 6 is on enhancing the accessibility of your Domino
applications by enabling you to:
v Share, lock, and edit design elements
v Provide nontraditional means for accessing your applications
v Communicate across platforms

Applications
Domino applications enable people to share, collect, track, and organize information, using Lotus Notes®
or the Web. Using Lotus Domino Designer, developers can create applications to meet a variety of
business needs, including:
v Workflow applications that route information.
v Tracking applications that monitor processes, projects, performance, or tasks.
v Collaboration applications that create a forum for discussion and collaboration.
v Data integration applications that work with relational databases and transactional systems.
v Dynamic applications that produce content based on, for example, user name, user profile, access
rights, or time of day.
v Localization and Management applications that use Domino Global WorkBench to translate Lotus
Domino databases and Web sites.

Databases
All Notes applications contain one or more databases. You create a database to use as the container for
the data, logic, and design elements in your application. Design elements include:
v Pages
v Forms
v Outlines
v Navigators
v Views
v Folders
v Framesets
v Shared Resources
v Agents

1
Starting Lotus Domino Designer
There are two ways to start Lotus Domino Designer from the Notes® client:
v From the Bookmark bar
v From a database
v From the command line

To start Domino Designer from the Bookmark bar in the Notes client
v

Click the Domino Designer icon on the Bookmark bar.

Note: If you do not see the Domino Designer icon, Domino Designer may not be installed on your
system.
The customizable welcome page of Domino Designer displays.

From the Domino Designer welcome page you can open an existing database or create a new one. When
you open a database, either a new or existing one, the Domino Designer Work pane displays.

To start Domino Designer from a database in the Notes client


If you already have a database to work with, you can start Domino Designer directly from that database.
You must have Designer or Manager access to the database in the ACL.
1. Open the database.
2. Choose View - Design.

Tip: You can also right-click the database icon on the Bookmark bar and select Open in Designer from
the list.

To start Domino Designer from the command line


Note: You can only use this method if you have already opened Designer and know the Replica ID of a
database and Note ID of a document in that database. Also, the user whose Notes ID is used when Notes
is launched must have at least Designer access to the database.

You can open a specific database in Domino Designer by entering its Replica ID and a Note ID in the
command line.
1. From the MS-DOS prompt, switch to the Notes directory.
2. Enter either:
v designer Notes:///Rep_id/Note_id (for a local database)
v designer Notes://Server_Name/Rep_id/Note_id (for a hosted database)
where Rep_id is the Replica ID of the database(do not include the colon), Note_id is the Note ID of a
document in that database(include only the characters that follow the NT and the series of zeros that
make up the ID), and Server_Name is the name of the server/database as it appears in the Design
pane, with the server name, followed by a slash, then the database name.

From Designer, you can find a database’s Replica ID by opening the Database Properties box. The Replica
ID, which is a series of numbers and letters, for example, 85256BE5:0051F014, is listed on the Info tab.
From Notes, you can find the Note ID for a document by opening the Document Properties box. The

2 Application Development with Domino Designer 7


Note ID, which is a series of numbers and letters following the letters NT, for example, NT000002AA, is
listed on the Document IDs tab. Given these Replica and Note IDs, you could open this database if it was
local by entering:
designer Notes:///85256BE50051F014/2AA

To open this database (named customer.nsf) hosted by the Casco/Bay server, enter:
designer Notes://Casco/customer.nsf/85256BE50051F014/2AA

Alternatively, you can use LotusScript to retrieve the Replica ID of a database and Note ID of a
document. You can also use the formula language @functions @ReplicaID and @NoteID to retrieve them.

Exploring Lotus Domino Designer


Building a great application requires the right tools. You can think of Domino Designer as your workshop
-- it contains all the tools you need to build a powerful application. Before you start building, examine
the work area.

Item Purpose
Design action buttons These convenient buttons trigger common tasks, such as creating new design
elements.
Design list Displays a list of the design elements or resources that are stored in the current
database. This list displays in the Work pane. When you click a list item, the Work
pane changes to display the work area for the selected element or resource.
Design pane Displays the design elements and resource types that a database can contain. If
you click an element, such as Pages for example, a list of the pages stored in the
current database displays in a Design list on the Work pane. The Design action
button at the top of the Design list for Pages enables you to create a new page.

Chapter 1. Introduction to Domino Designer 3


Item Purpose
Designer bookmarks Listed along the left side of the welcome page, bookmarks help you to quickly
access and organize your databases. You can drag a database onto the bookmark
pane to bookmark it or you can create a folder on the bookmark pane to which
you can drag related databases. By default, Designer provides a Recent Databases
folder. You can create additional bookmarks and folders.
Menu bar Presents context-sensitive menus of Designer commands.
Preview buttons Launch a browser to preview your work.
Properties box button Opens the Properties box for the active design element.
Window tabs Let you navigate among the open windows in your workspace.
Work pane When a design element or resource type is selected in the Design pane, displays
the Design list. When an element or resource is selected from the Design list,
displays two sections. The upper section contains the Work area for the element or
resource. The lower section contains the Programmer’s pane, which is shown in
the illustration below.

Item Purpose
Info List Scrollable window that displays the objects and coding reference information for the
design element currently displayed in the Work area.
Objects tab Lets you navigate between objects and events in the Programmer’s pane. To work on
an object, select it to expand its list of properties and events. If you select a property
or event, the script area of the Programmer’s pane changes to show the code that
describes it. Events and properties that are already programmed appear in a darker
color.

4 Application Development with Domino Designer 7


Item Purpose
Reference tab The Reference tab of the Info List is language sensitive; the contents of the Reference
tab change depending on the language selected. If you are editing in the Formula
language, the window contains @commands, @functions and fields. If you are
editing in LotusScript, the window contains LotusScript information. If you are
editing in JavaScript, the window contains information about the Document Object
Model. If you are editing in Java, the window contains Java-related information.
Script area Lets you enter formulas in the Script area. Formulas can be written in Formula
language, LotusScript, JavaScript, or simple actions.

Note that you can print source code by selecting File - Print when you are in the
Programmer’s pane. You can print any code you can view in the Programmer’s
pane.

Properties boxes
Properties boxes are tools you use to select or modify settings for a design element. Properties boxes have
tabs and each tab presents different attributes or options. If you hold the cursor over the icon on a tab,
the name of the tab appears. In most windows, right clicking opens the Properties box for the active
design element. You can also choose Design -- <element> Properties from the menu.

Properties boxes are context-sensitive so you can leave them open on your workspace and they will
change to reflect the element that you are working with.

Tip: You can also collapse some Properties boxes into context-sensitive tool bars by double-clicking the
top of the box.

Chapter 1. Introduction to Domino Designer 5


Creating a database
There are three ways to create a database:
v Using a template.
The fastest way to create a database is to use one of the Domino templates included with Domino
Designer. Domino Designer includes templates for creating a variety of applications. Applications
created using one of the Domino Designer templates can be used as is or customized.
To decide if there is a template that is right for you, see the Table of Domino Designer templates.
v Copying an existing database.
If you have access to a database that already has all the elements you are looking for, you can copy the
design and create a new database with the same features. Once you have created the database, you can
customize it to meet your company’s needs.
v Building your own.
If you need to create a unique database, build your own. Choose File - Database - New from the
Domino Designer menu. Name the database, select Blank from the template list, and click OK. This
creates an empty database in which you can create your own design elements.
For more information, see the chapter, ″Creating an application.″

Displaying, collecting, and storing information


How you display, collect, and store information is an important part of any application. The design
elements you use to accomplish these tasks are:
v Pages
v Forms and documents
v Fields

Starting in Lotus Domino Designer Release 6, you can use layers on pages and forms. Arranging fields,
buttons, and other UI content on a layer enables you to develop your page or form content in chunks
that can then be easily organized and quickly rearranged.

Pages
A page is a database design element that displays information. Pages are a familiar Web concept. Almost
every Web site has a home page -- a page that contains information about the company, graphics that
enhance the page, and links that take you to other places within the site or elsewhere on the Web.

6 Application Development with Domino Designer 7


Pages can be used anytime you are displaying information to the user. Pages can contain:
v Layers
v Text
v Tables
v Graphics
v Applets
v Embedded objects such as views
v Links

Pages often work in conjunction with framesets to display graphics, site navigation, or applets.

For more information on layers, see the chapter ″Designing Pages.″

Forms and documents


Forms, like pages, display information. Everything that can be done with a page can be done with a
form. What sets forms apart from pages is that forms can be used to collect information. A form provides
the structure for creating and displaying documents. Documents are the elements that store data in the
database.

Chapter 1. Introduction to Domino Designer 7


When you create a form in Designer, users can open the form in the Notes client from the Create menu.
On the Web, you must provide a button or action that opens the form. When the user completes the form
and saves it, the information is saved as a document. When a user reopens the document, the document
uses the form as a template for displaying the data.

For more information on forms and documents, see the chapter ″Designing Forms.″

Fields
Fields are the elements on forms that collect data. Each field on a form stores a single type of
information, which is stored in documents. A field’s data type defines the kind of information a field
accepts.

You can create fields in the following data types:


v Text
v Date/Time
v Number
v Dialog List
v Check box
v Radio button
v Listbox
v Combo box
v Rich text
v Authors
v Names
v Readers
v Password
v Formula

8 Application Development with Domino Designer 7


v Time zone
v Rich text lite
v Color

You decide if a field is editable -- that is, populated by user input, or calculated by formulas. You can
program fields to retrieve data from other Domino applications or from external sources. In addition, you
can create shared fields, which can be used in many forms within the same database.

For more information, see the chapter ″Designing Fields.″

Organizing your data


You organize the documents in your database using:
v Views
v Folders

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

For more information, see the chapter ″Designing Views.″

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

For more information on folders, see Lotus Notes 6 Help.

Chapter 1. Introduction to Domino Designer 9


Creating navigation
Every application needs to include a way to navigate from one place to another. You add navigation to
an application using:
v Outlines
v Navigators

When you create a new database from a blank template, Designer provides a default navigation structure
called the Folder pane (sometimes called the Navigation pane). The Folder pane displays all the shared
views and folders in the database. It displays on the left pane of the Notes client and on the top left of a
browser window. You can choose to use this navigation structure or design a different one.

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

You can also use an outline to plan your application before you create any design elements.

For more information, see the chapter ″Designing Outlines.″

10 Application Development with Domino Designer 7


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

For more information, see the chapter ″Designing Navigators.″

Structuring your display


For an application interface to be intuitive and efficient, it must make good use of the user’s screen. One
way for a designer to accomplish this is to use framesets.

A frameset is a collection of frames. A frame is one section, or pane, of the larger frameset and is
independently scrollable. By using framesets, designers can create links and relationships between frames.
Framesets let you leave one page displayed as users scroll or link to other pages or databases. There is no
HTML required to design a frameset.

Designer lets you:


v Create an effective multi-paned user interface for your applications.
v Control frame attributes such as size, scrolling, border colors and width, and frame spacing.
v Determine frame source content at runtime.
v Create programmable links that are maintained automatically.
v Set a frameset to launch automatically when a database, form, or page opens.
For more information, see the chapter ″Designing Framesets.″

Adding automation
Adding automation to an application can speed up repetitive tasks, route documents, update information,
perform calculations, run programs, and check for errors.

Chapter 1. Introduction to Domino Designer 11


You can add the following automated components to the design elements in a Domino application such
as a database, a view, a form, or a document:
v Actions
v Hotspots
v Agents

Actions
Actions automate tasks that are found on Notes menus or tasks defined by formulas or a LotusScript
program. Users click a button, hotspot, or pick from the Action menu to execute the action. For Web
applications in particular, use actions to simulate Notes menu items.

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

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

For more information, see the chapter ″Adding Automation to Applications.″

Sharing, locking, and editing design elements


Notes is a powerful tool because it helps developers work collaboratively. Lotus Domino Designer
Release 6 enhances team work by enabling developers to:
v Edit multiple design elements
v Share resources across databases
v Lock design elements

Editing multiple design elements


With Lotus Domino Designer 6, you can now update or edit properties of all the instances of a particular
design element that occur in a database. For instance, you could update or edit the following element
properties:
v Hide/when formulas
v Template inheritance settings
v Design refresh settings

For example, you can update all the forms in a database to hide them from the Notes client.

For more information, see the chapter ″Completing an Application and Managing Design Changes.″

Sharing resources across databases


By sharing resources, the development work of one team member does not have to be rewritten
elsewhere in the application, but can be directly incorporated as is, or can be incorporated, then tweaked
by another member of the team to suit the purposes of a different area of the application.

12 Application Development with Domino Designer 7


Lotus Domino Designer 6 increases the number of resources that can be shared in a database to include:
v Style sheets
v JavaScript libraries
v Non-NSF files

Locking documents and design elements


In Lotus Domino Designer 6, not only can you share elements within a database, but you can also share
them across databases. Because access to design elements has increased, Notes now lets developers lock
the elements they design. This prevents two or more team members from making changes to one element
at the same time.

For more information on locking design elements, see the chapter ″Completing an Application and
Managing Design Changes.″

For more information on document locking, see the chapter ″Creating an application.″

Autosaving Notes documents


Autosave is a Notes Client feature by which Notes documents are automatically saved to a local database
at regularly scheduled times determined by the user. If Notes crashes, or if the user loses power, the user
can recover the work that was done prior to the crash or power loss.

If the user enables the AutoSave feature, the most current version of the document is saved to an
Autosave database (...\data\autosave.nsf). The Autosave database is created automatically when the
Notes client is first installed. The user then recovers the documents from this database.

Note: Users can override the default location for autosave.nsf by setting the Notes.ini variable
auto_save_db to the file location of their choice.

Note that the original Notes document is still stored in its database or Notes application; the version with
the newest changes that has not yet been saved is the one copied to the Autosave database.

Enabling AutoSave in forms


In order for a document to be autosaved, the form from which the document is created must be enabled
for Autosave.
v Open the form’s Properties infobox
v On the Information tab, under Options, select ″Allow Autosave.″

Note: Application developers should be sure to test the forms in their applications with Autosave to
ensure that Autosave works properly with the application.

Enabling AutoSave in the Notes client


You enable AutoSave in the Notes Client User Preferences.

Note: The form on which your document is based must be enabled for AutoSave by the application
developer. If you enable Autosave in the Client, the client status bar will indicate when a document is
being autosaved. If Autosave is not enabled for a particular form, speak with the application developer
for that application about enabling Autosave.
1. Click File - Preferences - User Preferences.
2. On the Basics pane, under Startup Options, enable ″AutoSave Every 15 Minutes.″

Note: the default Autosave time is 15 minutes.

Chapter 1. Introduction to Domino Designer 13


3. (Optional) Increase or decrease the autosave interval.
4. Click OK.

Recovering documents saved with the AutoSave feature


Users can recover autosaved documents immediately upon startup, or at a time of their choosing.

At startup after a crash or power loss, and after the user authenticates, the user is prompted to recover
unsaved work with the message ″You have x unsaved document(s). Do you want to recover these
documents now?″

If the user presses Yes, the Recover Unsaved Documents dialog box appears that lists the documents that
can be recovered.

From the Recover Unsaved Documents dialog box, users have the following options:
v Recover - recover the selected document
v Recover All - recovers all documents without prompting for each one
v Remove - removes the selected document from the Autosave database
v Remove All - removes all documents from the local database

Alternatively, the user can press No at the recovery prompt, and recover the autosaved documents later
by selecting File - Autosave - Recover Autosaved Documents. The Recover Unsaved Documents dialog
box appears and users can recover or delete documents as described above.

Once a document has been recovered from the AutoSave database, it is automatically removed from that
database. This helps keep the Autosave database from becoming too big.

Other Autosave options


Note: These options only work if the form has been enabled for AutoSave.

Occasionally users may be in the middle of editing a document and need to save the document
immediately. They have the option of saving the current document to the AutoSave database by selecting
File - AutoSave - Autosave Now.

Users have the option of keeping a copy of the working document in the Autosave database until they
choose to delete it by selecting File - AutoSave - Save a copy to the Autosave database.

Extending access to applications


Domino applications are now more easily accessible to outside tools both during the design process and
after application completion and deployment.

With Lotus Domino Designer 6, you can:


v Use third-party design tools in Designer
v Use WebDAV for remote development
v Access an external data source from a field
v Bring an application offline
v Instant message colleagues

Using third-party design tools


With Lotus Domino Designer 6, you can launch third-party applications from within Designer. The
Designer menu bar has a new Tools menu option where you can save a link to a third-party application

14 Application Development with Domino Designer 7


as a ″tool.″ For example, you can now add a Web-development application, such as Dreamweaver, to the
Tools menu as a tool named ″Web work,″ for example. If you want to add HTML to your Designer
application using Macromedia Dreamweaver, you can launch it by selecting ″Web work″ from the Tools
menu.

For more information on customizing the Designer Tools menu, see the chapter ″Developing applications
using third-party tools and WebDAV.″

Using WebDAV for remote development


WebDAV (Web-based Distributed Authoring and Versioning) is a technology that allows users with
Designer access to a database to work with file-based design elements such as HTML pages, images and
style sheets, using WebDAV-enabled development tools on the Web.

By making Domino WebDAV compliant, the methods you can use to enhance file-based design elements
are extended. Lotus Domino Designer 6 lets you decide which tools to use to develop your applications.

For more information on editing and managing database resources using webDAV, see the chapter
″Developing applications using third-party tools and WebDAV.″

Accessing external data sources from a field


With Designer, you can use data connection resources to set up a connection between a field in an NSF
database document to a field in an external data source. The external data source can be a relational or
transactional database, which means you can now access enterprise data using a Notes application.

For more information, see the chapter ″Connecting to Enterprise Data.″

Bringing an application off-line


Access to Designer is now available to off-line users thanks to Domino Off-Line Services (DOLS). DOLS
enables a user to take a Domino Web application off-line, make changes or additions, and then
synchronize the off-line replica of the application with the original. The user does not even have to have
Notes since the application can be accessed via a Web browser. This capability greatly increases the ways
in which an application’s audience can access it.

For more information on DOLS, see the chapter ″Enabling an application for Domino Off-Line Services.″

Instant messaging colleagues


The Lotus Instant Messaging product is a powerful tool for enabling real-time communication between
team members. With Lotus Domino Designer 6.5, you can integrate Lotus Instant Messaging into your
Domino applications.

For more information on adding instant messaging to an application, see the chapter ″Creating an
application.″

Communicating across platforms


With Release 6, Domino data can be shared across platforms because Domino supports two of the most
widely used, multiple platform technologies:
v JavaServer pages (JSPs)
v Extensible Markup Language (XML)

JavaServer pages
You can now retrieve Domino data from an NSF database for use in a JavaServer page (JSP). Domino
Designer Release 6 includes custom tag libraries that you can include in your Web site directory files.

Chapter 1. Introduction to Domino Designer 15


These libraries are made up of several JSP tags. JSP tags are similar to HTML tags, except that they
contain instructions for executing complicated Java programming logic, instead of instructions for
defining how to format the contents of the tag. The logic in the Domino tag library is specifically
designed to retrieve, edit, and otherwise manipulate Domino data, but the complicated logic itself always
takes place behind the scenes. Once the libraries are included in a page, all the page developer has to do
is include a tag in a page and all the programmatic capabilities of the tag are automatically available.

Note: The JSP containing the Domino custom tag libraries must be hosted by a server that provides a
rich J2EE Web development environment, like the IBM WebSphere® Enterprise Edition server or
Application server 4.02.

For more information, see the book Domino Designer Programming Guide, Volume 1.

XML
Domino data can now be exported and imported from a database as XML. XML, the Extensible Markup
Language, is a meta-language that enables you to define data using tags. XML tags are similar to HTML
tags, except that they define the content within a tag, instead of defining how to format the contents of a
tag.

Since you can export data from a Notes database as XML, it can then be transferred to other platforms.
Once each platform agrees on a set of XML tag definitions, transferring the data between them or
transforming it via a style sheet for optimum display on various devices, is easy.

For more information on viewing XML using DXL utilities, see the book Domino Designer Programming
Guide, Volume 1.

For information on using XML with Domino, see the book Domino Designer Programming Guide, Volume 1.

For more information on the Domino DTD tags, see the book Domino Designer Programming Guide, Volume
1.

16 Application Development with Domino Designer 7


Chapter 2. Planning an application
Before you begin any design work, create a plan for how users will access and use your application. At
the minimum, your application plan should address these questions:
v Will users access the application from a Notes client only , Notes and a Web application , or Web
browser only?
v Do you need to tailor this application for use by mobile users?
v How can you make your application accessible to users with disabilities?
v Will the application be translated into multiple languages?
v What demands will be placed on the application -- that is, will there be large views containing many
documents?
v What are the performance expectations for the application?
v How will users know how to navigate and use the application?

The more planning you do before design begins, the smoother the design process will be. Designer
provides you with a range of tools and services to suit your design needs and application development
styles.

Planning a Notes application


If your application is only intended for use by Notes clients, use the standard design elements provided
by Domino Designer. When programming, consider using the Notes formula language and LotusScript®,
both of which were designed for use with the Notes client.

Planning a Notes and Web application


If you are planning an application that users will access via a Notes client or via a Web browser, you will
need to do some design work to tailor your application for each platform. For example, a navigation
structure that is suited for a Notes client application may not be the best choice for a Web application.
When you design an application for both Notes and Web, about 85% of your design will be suitable for
both clients, and the remaining 15% will require some modification. Here are some issues to consider
when planning an application for Notes and Web users:

Understanding the differences


The division of labor in a Notes application -- what the Domino® server does and what the Notes client
does -- is very different from the architecture of a browser-based application. This is because the
capabilities of a Notes client are very different from a Web browser, and the protocols the browser and
server use to communicate are very different as well.

Domino uses Sun Microsystems Java(TM) and JavaScript(TM) to translate Notes client functionality to the
browser with fuller fidelity, so that Web users can interact with action bars, rich text, views, and other
Notes features in familiar ways. But there is no Web functionality equivalent to the Notes Document
Object Model (DOM) and Remote Procedure Call (RPC) protocol. A Notes client can send instructions to
the server to perform a task and receive back results that are refreshed within the current open form or
document. This kind of interaction is nonexistent between a browser and server. All a browser can do is
send a request to a server, and all a server can do is send a complete page to a browser.

Limitations of the Web browser and the browser/server architecture are the basis for most of the
problems you must solve as you consider how to serve one application to Notes client and Web browser
users.

17
Tips for designing Notes and Web applications
The following are some areas to consider when planning an application for both Notes and Web clients.

Security
The security model is different for Notes and Web users. Manager and Designer access to databases is not
available for Web users as it is for Notes client users. Therefore, do not include LotusScript actions or
agents that require a user to have Manager or Designer access to complete the task.

Authenticating users requires extra planning for applications available via Web browsers. Most Web
applications provide some level of access for Anonymous users. For higher levels of access, you must
match Web users to the names in the Domino Directory. Because Web users generally login to an
application using an abbreviated name, consider using the @UserName command to return their fully
distinguished Notes name for proper authentication.

Forms
Many times the same form will work in both a Notes client application and a Web application. You can
compensate for minor differences in functionality using hide-when formulas for design elements on a
form. At times you may want to display one subform for a Notes client and another for a Web browser.
In this example, the formula calls one of two computed subforms named NS and IE that include
browser-specific code by using the CGI variable for browser type in @BrowserInfo:
@If(@BrowserInfo("BrowserType")="Netscape";"NS";"IE")

Each subform has its own JavaScript Header, so you can selectively include JavaScript as well as other
data types in your forms by using computed subforms.

All subforms open simultaneously with the main form. You can’t display a computed subform on the
basis of calculations after the page opens.

Forms are quite flexible in a mixed-client environment. Using programming designed to support multiple
clients, you can program a form event to execute one set of commands when accessed by a Notes client
and another set of commands when accessed by a Web client. In some cases, you may find it easier to
design two completely separate forms -- one for a Notes client, and another for a Web client. In this case,
you assign the same alias to the two forms, hide one from the Notes client, and the other from the Web
client, so that the correct form displays in the correct context.

Fields
Consider that not all field types that are supported in a Notes application are supported in a Web
application. For example, the Web does not support a multivalue keyword field that allows users to enter
choices not in the list. The workaround for this is to use two fields in a Web application -- one field to
accept new choices for the list and the other field to build and display the list. If users can access the
application from either the Notes client or the Web, you must synchronize the field values so that all
users see the same values.

If you can solve a problem with two versions of a field formula, one that works in Notes and the other
that works on the Web, then include both in the form and use the ″Hide from Notes/Hide from Web
browsers″ selection in the Field Properties box to display one or the other.

If you’re using the same form for both Notes clients and browsers, the ″Hide from Notes/Hide from Web
browsers″ attribute on a design element’s properties can be very useful. However, note that ″hidden″ has
a different meaning for each client. In Notes, hidden fields are still present in the document and can be
used in scripted calculations. Fields hidden from Web browsers, on the other hand, are cut out of the
document by Domino before the page is served to the browser. The field contents are not available to be
used by JavaScript.

18 Application Development with Domino Designer 7


Tip: If you want to make fields invisible in a browser, but keep their contents available to JavaScript,
don’t use the ″Hide from Notes/Hide from Web browsers″ and don’t put ″type=hidden″ into the fields’
HTML Body Attributes objects. Make sure that:
v Their hide-when properties are set correctly for the Notes client.
v ″Use JavaScript when generating pages″ is set in the Database Properties box.
v ″Generate HTML for all fields″ is selected in the Form Properties box.

Domino will generate the appropriate <type=hidden> tags in the HTML page:
<input type="hidden" name="fieldname" value="fieldcontents">

Be aware that names and values treated this way are not secure. They can still be seen by any user who
clicks on the browser’s ″View Page Source″ function.

Remember, too, that not all fields can be passed to a browser this way -- the password field, for example,
″$Updatedby,″ ″$HtmlHead,″ and any objects that contain NULL characters (which includes users’ public
keys) because NULLs cannot be expressed in HTML.

Actions
Actions play a more significant role in Web applications because Web browser users do not have access to
the Notes menu commands. You must supply an action for tasks such as creating a document, switching
to Edit mode, switching views, or forwarding documents. Therefore, in many cases you must design an
action bar specifically for a Web application that you hide from Notes client users.

Tip: To Web-enable buttons in a database, check ″Web access: Use JavaScript when generating pages″ in
the Database Properties box. If this property is not 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.

Views
Displaying Notes views in a Web application results in a loss of some display attributes unless you first
embed the view on a page. You can embed multiple views on a page to achieve a sophisticated layout.
You can also specify a view template that will apply uniform style properties to embedded views for use
in Web applications.

For more information, see the topic ″Displaying views in Web applications″ in the chapter ″Designing
Views.″

Navigation
Using an outline for navigation can provide a uniform structure for Notes client and Web browser users.
An outline lets users open views, pages, or URLs. Embed the outline on a page to preserve all of the
display properties for Web browser users.

You might also consider an imagemap as a navigation tool.

For more information, see the chapter ″Navigating an Application″ later in this book.

Agents
Programming with agents provides all of the processing power for an application. Using agents is where
you will encounter the most significant differences in developing applications for Notes client and Web
browsers. Although you should be able to share a lot of code, there will be instances when you need to
write certain agents for the Web, and certain agents for the Notes client. The key programmable server
events for Web applications are WebQueryOpen and WebQuerySave. To avoid performance problems, use
these events to perform key tasks, and use background agents to perform more complex processing.
Agents can be run from the Web using @Command([ToolsRunMacro]) or @URLOpen formulas.

Chapter 2. Planning an application 19


By default, Web agents run under the identity of the agent author (the person who saved the agent). To
run agents under the identity of the Web user, open the Agent Properties box, click the Design tab, and
select ″Run Agent as Web user″ option in the For Web Access section. This option can provide more
security, because when a Web user tries to run an agent with this property set, Domino prompts the user
for a name and password and checks them against the invoker’s rights in the database ACL.

In the Notes client, many form, field, and button events can be scripted in either JavaScript or LotusScript
(or, to be sure, @formulas). Depending on how your application uses scripted events, this may mean that
you write your agents using JavaScript and use the same form for both Notes and Web clients. There are
differences in the capabilities, however. JavaScript in the Notes client has access only to the data in the
currently open form -- it lacks the access to the front-end and back-end Domino Objects of LotusScript.
Your application may work best if you write LotusScript for execution in the Notes client and JavaScript
for browsers, and use hide-whens or separate forms to keep the execution straight.

Keep in mind that many @functions and @commands don’t work in a browser. The @functions that don’t
work fall into three major categories:
v They work only in the Notes client interface. There are no browser counterparts to @DialogBox,
@Picklist, and @Prompt, for example. And several advanced mail-handling functions are unique to the
Notes client, such as @MailSend and @IsDocBeingMailed.
v The much simpler structure of Web views doesn’t support many functions, including @DocChildren,
@DocLevel, @DocNumber, @IsCategory, or @Responses.
v Many features associated with Notes access, preferences, and the workstation environment don’t carry
over to a browser -- @Certificate, @IsAgentEnabled, @MailEncryptSavedPreference, and
@UserPrivileges, for example.

Most @commands are associated with controlling the Notes client interface, so they don’t work in Web
applications. The handful that do work on the Web work hard, though, because they’re used often.
@Command([FileSave]) and @Command([FileCloseWindow]), for example are used frequently together to
simulate a Submit button.

You can check to see whether @formulas and properties of other programming constructs work for the
Web by looking through the topics listed in the appendix ″Overview of features to avoid using in Web
applications.″

Replacing dialog boxes for Web applications


You should consider designing forms for your application to replace error messages and Help dialog
boxes that are missing on the Web. Particularly if you require users to authenticate in order to use your
application, you should create a $$ReturnAuthenticationFailure form to inform users that authentication
failed and give them links they can use to navigate back to familiar territory in the application.

Create your form and save it with the name $$ReturnAuthenticationFailure. In order to make this form
available for public access, you must do two things. First, you must set the Default role in the Access
Control List to read public documents.

Second, set the form’s security properties to make it available to public users by choosing ″Available to
public Access Users″ on the Security tab of the Form Properties box.

There are four reserved form names that you can use to create customized error messages for browser
users: $$ReturnAuthenticationFailure, $$ReturnAuthorizationFailure, $$ReturnDocumentDeleted, and
$$ReturnGeneralError.

For more information about these fields and how to use them, see ″Displaying a customized error
message″ in the chapter ″Designing Forms.″

20 Application Development with Domino Designer 7


Programming for multiple platforms
You can now program the same event in Designer for the Notes client and the Web browser. You can
optimize the code in an event -- for example, the Click event of a button -- for the platform it will run on.
Code you supply for the Client platform executes when a user runs the application in the Notes Client.
Code you supply for the Web platform executes when a user runs the application in a browser. These
dual platform events are available for selected events on Forms, Pages, Subforms, Fields, Buttons,
Actions, and Hotspots.

Planning for browser differences


If your users will be accessing Web applications using different browsers or different versions of
browsers, you must test your application accordingly and tailor it for browser differences. In cases where
you need to code around differences between browsers, you can use @BrowserInfo to help you determine
what browser or version the user is running.

For more information on @BrowserInfo, see the Domino Designer Programming Guide.

Planning for integration with WebSphere and DB2


You can use Domino Designer to build applications that exploit the collaborative features of the Domino
server as well as the transactional power of the WebSphere® server and the data storage capacity of a
DB2® database, resulting in end-to-end business solutions for applications such as supply chain
management, sales force automations, or customer relationship management.

Using Java technologies such as Overview of Java servlets, you can share code with and link to
WebSphere applications. Single Sign-On (SSO) -- a shared authentication service -- allows for further
seamless integration between Domino and WebSphere applications.

For more information on using Single Sign On, see Administering the Domino System.

Planning a Web application


Perhaps your widest range of design options is available when designing an application that will only be
accessed via a Web browser. You can build a Web application using the full range of Designer features
and tools, or you can build an application using the latest Web technologies. This range of tools and
features, coupled with all of the benefits of a Domino application -- such as the security model and
replication -- give you the most control over the design and delivery of an application.

Designer features with special relevance for developing Web applications include:
v An HTML editor
v HTML-rendering for design elements
v JavaScript libraries
v Imagemaps and outlines for navigation. Note that large graphics used in imagemaps can present a
performance problem for Web applications.
v Pages
v Applets
v Style sheets for transforming HTML and XML

Java features include:


v Java servlets
v Support for Web-based Distributed Authoring and Versioning (WebDAV)

Chapter 2. Planning an application 21


Tips for designing Web applications
Databases viewed from a Web browser may look somewhat different than they do when viewed from the
Notes client. Browsers render design elements with slight differences. Be sure to preview your database
through each browser that will access it so that you can make adjustments to your design. Also, for
databases that will be accessed through Web browsers, it is best to:
v Make sure the database is in the Domino Data directory or a subdirectory of the Data directory.
v Add form actions. such as Create, Edit, and Save.
For more information, see ″Actions″ in the chapter ″Automation in Applications″ later in this book.
v Avoid using featuresthat aren’t supported in Web Applications.
Refer to the appendix ″Features to Avoid Using in Web Applications″ later in this book.
v Use additional @commands and/or create multiple buttons on a form by selecting the database
property ″Web access: Use JavaScript when generating pages.″
v Change from the Lotus Software color palette to a Web color palette to provide greater color fidelity on
the Web. To change palettes, choose File - Preferences - User Preferences. Check ″Use Web Palette″ on
the Advanced options list of the Basics page.
v Set views, outline controls, action bars, and rich text fields to be displayed as Domino applets when
viewed with a browser.
For more information, see the topic ″Domino Applets.″
v Check the Access Control List (ACL) setting to make sure it allows appropriate access for Internet
users.
For more information, see ″Setting up database access for Internet users.″
v Prevent users from accessing forms and views in a Web application by selecting the database property
″Don’t allow URL open.″

Creating formulas and buttons for the Web


To use certain @commands or create multiple form buttons for Web applications accessed on the Web,
select the database property ″Web access: Use JavaScript when generating pages″ on the Database Info
tab of the Database Properties box. To open the Database Properties box, open or select the database and
choose File - Database - Database Properties.

Note: There is no Web Formula module in the new dual platform event model. If you write Client
Formula code to perform an action in a Web application, check the Hide option ″Notes 4.6 or later
clients″ on the Hide tab of the properties box for the element you are programming.

Web application performance tips


Selecting the ″Web access: Use JavaScript when generating pages″ affects display, buttons, and
@commands throughout the application in the following ways:

If you select ″Use JavaScript″ If you don’t select ″Use JavaScript″


Display: Documents and navigators display faster Display: Documents and navigators display more slowly
because hotspot formulas are not evaluated until users because the hotspot formulas are all evaluated at the
click each hotspot. display time.
Buttons: Domino doesn’t generate a Submit button Buttons: Domino automatically generates a Submit button,
automatically. at the bottom of the form.
To allow users to save and close a form on the Web, If there is already one or more buttons on the form,
you must create a button, hotspot, or action that Domino converts the first button it recognizes to a Submit
contains these commands: button automatically and ignores all other buttons on the
form.
@Command([FileSave]);

@Command([CloseWindow])

22 Application Development with Domino Designer 7


If you select ″Use JavaScript″ If you don’t select ″Use JavaScript″
You can have multiple buttons on a form. You can have only one button, a Submit button, on a
form.
@Commands: The following commands are supported @Commands: The following commands are not supported
on the Web: on the Web:

@Command([CloseWindow]) @Command([FileSave]) @Command([CloseWindow]) @Command([FileSave])


@Command([ViewRefreshFields]) @Command([ViewRefreshFields])
Domino does not check the formulas before displaying Domino checks the formulas before displaying pages.
pages. Actions that contain unsupported @commands or
@functions will not be displayed on the Web.

Planning an application for mobile users


You may want an application you design for Notes or Web users to be available to mobile users. You can
easily tailor an existing application for Mobile Notes(TM) users by excluding certain design elements
from a mobile application to streamline it for better performance. For example, you may to exclude a
large, complex view or a graphical navigator from the design elements that get served to mobile users to
avoid performance problems.

You can specifically exclude design elements by using the option ″Hide design element from Mobile
clients″ option on the Design tab of the Design document properties box. You can set this property for
multiple elements by holding down the Shift key while selecting elements from the design pane, then
choosing Design - Design Properties to display the Design Document properties box.

For more information, see ″Hide-when options for all applications.″

Hide-when options for all applications


Designer lets you hide many of the design elements and components of an application according to the
context you specify. You can hide design elements from certain types of users to help you tailor an
application for use by Notes, Web, or Mobile clients. You can also hide individual design elements
according to a particular context you specify. If hide options are available, the Hide-When tab appears on
the properties box for that element.

You can hide elements, including their text, graphics, and fields, in any of these situations:
v When users read, hide information that is useful only when users create or edit documents.
v When users edit, print, and copy, hide information that is useful when users read documents.

To set hide-when options on one or more elements according to client


type
1. Select a design element in the design pane. To select multiple elements, hold down the shift key while
you click to select multiple elements.
2. Choose Design - Design Properties.
3. On the Design tab, choose one or more hide options in the ″Hide design element from″ section.

To set hide-when options on individual elements according to context


1. Select the element you want to hide in the work pane and open the Properties box.
2. Click the Hide tab.
3. For basic options, select all situations in the ″Hide paragraph when document is:″ section where
components should be hidden from users. Consider the options in the following table.

Chapter 2. Planning an application 23


4. For programming options, select ″Hide paragraph if formula is true″ and write a formula in the
design pane to describe the situations in which users don’t need to see the layout region.

If an element is hidden when Then


Previewed for reading The hidden information isn’t visible when users read documents in the
document preview pane.
Previewed for editing The hidden information isn’t visible when users work on documents in Edit
mode in the document preview pane.
Opened for reading The hidden information isn’t visible when users open documents in Read
mode. A layout region that can’t be read can’t be printed either.
Opened for editing The hidden information isn’t visible when users work on documents in Edit
mode.
Printed The hidden information isn’t visible on printed documents.
Copied to the clipboard Hides the contents of the component when users copy a document. Note
that this setting does not affect documents copied at the view level.
Note: If you create or save a document from a form that contains a field
with ″Hide when copied to the clipboard″ checked and then copy the
contents of the document somewhere else, the contents of that field will not
be pasted.
Embedded The element isn’t visible when users access a document in which you have
used the embedded editor to embed the element.
Hide paragraph if formula is true A formula determines the circumstances in which information is hidden.

HTML tag attributes for a Domino server


The HTML tab appears on many properties boxes. If you are designing a Web application and are using
HTML 4.0, the HTML tab lets you apply core attributes that are common to a number of objects, such as
Cascading Style Sheet (CSS), easily. Domino incorporates the values of these attributes in the HTML that
it creates at runtime. When you are using the HTML tag attributes, remember:
v The HTML must be ASCII characters.
v Do not place quotation marks around the attributes, except around the attributes you use in the Other
box.
v The ″Other″ attribute needs quotation marks, as shown in the example below.

HTML tag attributes


HTML tag attributes Description
Name/ID References an object using JavaScript or CSS. For example, the object could be

ID = ZipCode
Class Applies a CSS class for a defined object. For example, if the object’s name is
ZipCode, the class could be Numeric. CSS styles are defined in the HTML Head
Content event for a form or page.
Style Applies a specific CSS style to an object using in-line CSS. For example, if the
object’s name is ZipCode, the class is Numeric, the style could be font-size:10pt. If
you have more then one value, separate them with a semi-colon; for example,
font-size:10pt; color:blue.
Title Explorer 4.x and later provides the user with a tip or prompt. For example, if the
object’s name is ZipCode, the class is Numeric, the title could be Enter your Zip
Code. The title displays differently on different browsers.

24 Application Development with Domino Designer 7


HTML tag attributes Description
Other Adds other HTML tag attributes, and must be written as pure HTML code. For
example, instead of writing ZipCode in the Name/ID box, you write ID=″ZipCode″
in the ″Other″ box.

Domino applets
When users run a Domino application from a Web browser, some Domino design elements are more
effectively presented to Web users using Java instead of HTML. Domino provides Java applets for these
design elements so that the interface is more similar to the Notes client interface. You can easily enable
the Java applets when you create the design element.

When you consider whether to use the Java applets or HTML, keep these points in mind:
v The applets provide a more interactive interface.
v The Domino applets require download time on the Web.
v The applets use the Java Developer’s Kit (JDK), Release 1.1.8 to support Java-enabled Web browsers.
The only fonts available are typically Courier, Helvetica, and Times.

For a complete description of how the applets work, see the description for each design element:
v Outline applet
The outline applet lets Web users work with outlines embedded in a page or form.
v View applet
The view applet lets Web users use many of the Domino view features, including column resizing,
multiple document selection, and section collapse/expand without page regeneration.
v Action bar applet
The action bar applet lets users scroll and easily view and select subactions.
v Editor applet
The editor applet lets Web users change the font, color, size, and style for text in rich text fields.

Designing an application for maximum accessibility


When designing an application, there are things you can do to make your application accessible to people
with physical disabilities. To meet federal accessibility guidelines, your application must be:
v Keyboard-accessible -- An application is keyboard-accessible if it can be used without a mouse or other
pointing device.
v Screen reader-accessible -- An application is screen reader-accessible if vision-impaired users can access
your application with screen readers. Screen reader software, in conjunction with a digital speech
synthesizer, provides an auditory representation of what is on the screen or what the cursor shows. In
order to function, the screen reader software must have detailed information about the graphical user
interface (GUI), so that it can translate the graphical display into speech.

The Notes client is both keyboard-accessible and screen reader-accessible. On those platforms which
support it, Notes uses MS Active Accessibility (currently only available on Microsoft Windows 95 and NT
4). Although many of the objects you create in Designer have the capacity to be made accessible -- for
example, you can provide descriptions, called ″alternate text,″ for images and applets -- it is possible to
create an application in Designer that is not accessible. And some design elements are not accessible.
However, the Domino server automatically generates accessible HTML whenever possible.

Design considerations for accessible applications


To create an application that is accessible to people with disabilities, keep the following design
considerations in mind.

Chapter 2. Planning an application 25


v Use text as the primary means of communicating information. Text and rich text are accessible in
almost every situation.
v Use the Alternate text tag on all images and applets.
Both images and Java applets allow you to specify a short piece of text to be displayed with the
graphical object. Typically the alternate text appears only when the object is loading or when image or
applet loading is turned off in browser preferences. However, alternate text is also used by screen
reader software to describe the contents of an object. Specify alternate text on the Info tab (i) of the
Picture and Java Applet Properties box.
v Echo the action button tasks in the Action menu and echo the forms you create in the Create menu.
Screen readers cannot always provide information about action buttons. For this reason, when you
design an application, you should provide users with an alternative way to trigger actions and create
forms. Echoing action button tasks in menus provides this alternative route. To echo an action button
on the Action menu, open the properties box for the action and select ″Include in Action Menu.″ To
provide access to a form that might otherwise be triggered by an action button in a view, for instance,
open the properties box for the form and select ″Include in menu.″
v Place the most frequently accessed menu items at the top of the menu list.
The vertical order in which the Action buttons appear in the action pane indicates the order in which
they appear on the Action menu and bar. You can create the order in which forms appear on the
Create menu. You can cut and paste the most frequently used actions to the top of the list in the action
pane. To place the form that is most often accessed by users at the top of the Create menu list, insert
the number 1 followed by a period (1.) in front of the name in the form’s name field. You can number
the remaining forms accordingly to control their order in the menu list.
v Check that the accelerator keys assigned to menu items make sense.
If an application has more than one menu item that starts with the same letter, Notes assigns a default
accelerator key using the first letter not already in use. If the accelerator key assigned to an action or
form does not make sense, you can force the assignment of a specific key. In the name field for the
action or form, add an underscore before the letter you want to assign as the accelerator key. For
example, if you want to assign p as the accelerator key for the form entitled Complete evaluation, enter
″Com_plete evaluation″ in the form’s name field.

Avoid:
v Using Java applets as the sole means of navigating or performing an action. Java accessibility is
currently not widely supported, and a keyboard-only user cannot navigate to a Java applet in many
browsers.
v Excessive use of embedded objects. Although these are keyboard-accessible, navigating through too
many objects can be a burden for keyboard-only users.
v Excessive use of framesets. It is laborious for keyboard-only users to navigate through framesets. The
fewer frames used in an application, the easier it will be for a keyboard user to navigate.
v Using color and graphics as the sole means of communicating meaning in your application. To test if
your application is legible for color-blind users, set your display to monochrome and view all graphics.
v Using text smaller than 10 point Helvetica. Some operating systems support a large font user
preference, but this preference is not respected by all objects in an application.
v Graphical navigators. Use outline controls instead as they are screen reader accessible.
v Layout regions.

If accessibility is a major priority for your application, you may want to consider creating an alternate
interface for your application using only text and non-embedded controls.

For more information about accessibility, see the following resources:


v The IBM Special Needs Web site at http://www.austin.ibm.com/sns/
v The W3 Web Accessibility Initiative (WAI) site at http://www.w3.org/WAI

26 Application Development with Domino Designer 7


v Customizing Designer for Accessibility

Creating multilingual applications


The following Domino features allow you to create applications that can support different languages.

Setting a default language and region


If you are creating an application that will have different language versions of some or all of its design
elements, select ″Multilingual Database″ on the Design tab of the Database Properties box. Then you can
select a default language and region. This property works in conjunction with the language preference
setting on users’ browsers. For example, if you have three versions of design elements in your database,
one in English, one in French, and one in Spanish, and the user’s browser or Notes client user preference
is set to Spanish as their default language, the Domino server displays the Spanish version of the home
page.

If you create a multilingual database and build design elements associated with particular languages, the
list of design elements displays a column identifying the language associated with the element.

Note: If you create an application for Macintosh users or users on another platform who do not have
Designer access in the database ACL, users will be unable to assign a language to a view or folder they
create. If the user creates a view or folder with the same name and alias as another view or folder in the
database, because the version the user created has no assigned language, when Notes attempts to discern
which language settings to use, the results can be unpredictable.

Creating multilingual design elements


You can design a multilingual database so that it includes copies of design elements for each language
you support. For example, if you are designing an expense tracking database for users in several
countries, you can design a copy of each form for each country in its native language. Use the following
steps to create copies of design elements such as pages, forms, views, or outlines.
1. Make sure your database is designated as multilingual. Select the database, choose Design - Design
properties, and check the ″Multilingual Database″ option on the Design tab.
2. Assign a default language and, optionally, a region.
3. Create a design element for the default language. When you name the element, assign it an alias. The
alias is the common point of identification for multiple copies of the same design element.

Note: Create one and only one alias for design elements in a multilingual database.
4. Make a copy of the design element and open the copy for editing in the Work pane.
5. On the Info (i) tab of the properties box for the design element, assign a name and an alias. The name
can be the same as the original design element or it can be unique; the alias must be the same.
6. Translate the text of the design element into another language and save and close the element.
7. Select the element name from the work pane and choose Design - Design Properties to open the
Design Document properties box.
8. On the Design tab of the Design Document properties box, select a Language and, optionally, a
Region to associate with the design element.
9. Select a corresponding sort order for the language or choose Unicode standard sorting.
For information on naming an element and assigning an alias, refer to the documentation for creating
that element. For example, see the topic ″Naming Forms″ in the ″Designing Forms″ chapter.

Translating an application using IBM Domino Global Workbench


Domino Designer includes the Domino Global Workbench, a fully integrated translation tool specifically
designed to facilitate the translation of Designer applications into a variety of languages.

Chapter 2. Planning an application 27


If you decide to use Domino Global Workbench, a number of design-stage tasks makes the localization
process simpler. For example, you should use aliases for the names of design elements wherever you can.
Use a system of standard prefixes for the aliases so that they can easily be identified as text to exclude
from translation. To launch Domino Global Workbench, click the Domino Global Workbench

icon.

For more information, see ″Preparing Source Databases″ in Domino Global Workbench Help.

Domino Global Workbench elements


Domino Global Workbench, a set of software tools that facilitates the localization (translation) of Domino
applications, consists of the following elements:
v The Workbench -- The Workbench extracts terminology from a database application and stores it in
glossaries, builds localized versions of the application using the translated glossaries, and if the
application changes, the WorkBench’s update features transmit the changes to the localized versions.
v The Glossary -- A Web-enabled Domino application that holds the terminology extracted by the
Workbench. Each item in the glossary has a unique ID, linking it back to its source database. The
glossary contains views and agents that assist translators (for example, by providing context
information), and prevent unnecessary work (for example, by making it easy to select and mark terms
as DNT (do not translate)).
v The Language Synchronizer -- In a multi-language application, such as an international Web site,
translation of documents is usually a requirement. New documents authored in one language must be
copied and then translated into the other Web site languages. The Language Synchronizer automates
much of this process.

Domino Global Workbench advantages


Domino Global Workbench provides the following advantages over conventional localization methods:
v Reuse of technical up-front investment. One technical person can do the initial analysis of the
application, define what needs to be translated and what should remain in the source language,
provide contextual comments for translators, and so on. This effort speeds the work of all translators,
who do not need to concern themselves with issues such as what should and should not be translated
(translators do not see much of the text that should not be translated).
v Efficient use of resources. Technical people perform technical tasks, whereas translators concentrate on
translation.
v Translation is done with full contextual information. Translators know what design element they are
translating and they can always trace it back in the source application.
v Reusability of translations. Because all translations are stored in glossary databases with full contextual
information, they can be reused in other applications that use similar terminology.
v Multilingual applications. You can build several translated databases from a single source, or you can
build one multilingual database with design elements in several languages. This simplifies the creation
of multilingual Web sites.

Domino Global Workbench features


Features in Domino Global Workbench include:
v Support for the localization of design elements
v Enhanced glossary functionality, including XML import and export, and Lotus Translation Component
(LTC) enabling
v Unicode support
v Support for the localization of external LotusScript files
v Support for the localization of XML content

28 Application Development with Domino Designer 7


For more information, see the following resources:
v The Domino Global Workbench Help
v The Lotus international Web site at http://www.lotus.com/international

Adding translation components to a Designer application


The Lotus Translation Components (LTC) are programming objects and server-based software services
that provide a secure, reliable, and robust environment to connect a set of heterogeneous translation
services to Lotus software and WebSphere-based platforms such as Domino, QuickPlace(TM), the
WebSphere Application Server and the WebSphere Portal Server. The LTC help IBM customers break
language barriers with their employees, partners, suppliers, and customers by providing an enhanced set
of linguistic services that facilitate the integration of third-party linguistic solutions.

Although primarily designed to work with machine translation software, such as the IBM server-based
machine translation engines, the LTC can connect to any third-party translation services that support the
Linguistic Services API (LSAPI) developed by IBM.

Because of their open architecture, the translation components allow developers to integrate translation
services rapidly and intuitively into Domino applications, facilitating communication across languages
and breaking language barriers in an ever-growing global environment.

The Lotus Translation Components consist of the following parts, which provide a connection to a
translation connector and its associated services:
v Domino Translation Object (DTO)
The DTO, provided by Lotus software, handles the API calls made from within a Notes or Domino
application to set up and activate a service request. It communicates with the Translation Services
Gateway (TSG).
v Translation Services Gateway (TSG)
The TSG serves as a connection between the DTO and the multilingual services provided by the
different third-party vendors. When the DTO is asked to provide information about the various
services available, it communicates with the specified TSG, which calls each of its services in turn,
collates the information, and passes it back to the DTO. When the DTO sends a request to the TSG, the
TSG determines which services are required and passes the request to the appropriate services or
connectors attached to it. The TSG also acts as a storehouse for various core services provided by Lotus
software, such as text filters or the ability to load and unload a service.

Lotus Translation Components Features


Features in Lotus Translation Components include:
v Improved install and startup procedures.
v Certification with Java 1.2 and 1.3.
v Support for AS400, AIX, Solaris and Linux platforms.
v A Web Administrator that allows translation gateways to be remotely configured from a browser.
v A servlet that allows a translation portlet to be incorporated into applications, making translations
accessible to users of browsers or Wireless Application Protocol phones.
v LiteTransObj (Java), a low-profile version of the existing TransObj class, suitable for use in an applet or
mobile device. A core service, ServiceLiteTransObj, supports the LiteTransObj class, creating a
micro-http server that listens for LiteTransObj requests and services them. LiteTransObj provides an
alternative transport layer to Remote Method Invocation.
v CLiteTransObj, a C++ / C version of LiteTransObj.

For more information, see the following resources:


v LTC User’s Guide
v LTC Reference Manual

Chapter 2. Planning an application 29


v The Lotus globalization Web site at http://www.lotus.com/international

Table of Notes and Domino known limits


The following table summarizes the known maximum limits of various Notes and Domino features.

Item Maximum limit


Database size The maximum OS file size limit -- (up to 64GB)
Text field size 32KB (storage); 32KB displayed in a view’s column
Rich text field size Limited only by available disk space up to 1GB
Response levels in a hierarchical 31 levels; 300,000 documents
view; number of documents per level
Characters in names Database Title: 96 bytes

Filenames: On Windows® and UNIX® platforms minimum of 255 and/or OS


limits; on local Macintosh workstation 31

Field names: 32

View names: 64

Form names: 32

Agent names: 32
Fields in a database ~ 3000 (limited to ~ 64K total length for all field names). You can enable the
database property ″Allow more fields in database″ to get up to 22,893
uniquely-named fields in the database.
Columns in a table 64
Rows in a table 255
Views in a database No limit; however, as the number of views increases, the length of time to
display other views also increases
Forms in a database Limited only by database size.
Columns in a view 289 ten-character columns; dependent upon # or characters per column
Documents imported into a view Documents totaling at least 350K
Cascading views in a database 200
Margin size (in inches) 46
Page cropping size (in inches) 46
Point size to select or print 250
Documents in a view Up to the maximum size of the database
Documents that can be exported to Limited only by available disk space
tabular text
Entries in an Access Control List ~950 names (ACL size is limited to 32767 bytes)
(ACL)
Roles in an Access Control List 75 Roles
ID password length 63 characters
Authorized users on a multiple 8 users
password ID
Outline entries in an outline ~21,000 entries

30 Application Development with Domino Designer 7


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

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

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

Creating a database from a template


Designer comes with a collection of templates that you can use to create applications. You can recognize
these templates by their NTF extensions. A template is a file that contains the structure for the database --
that is, pages, forms, and views -- but does not contain documents. For example, to design a discussion
database, use the Discussion template (DISCSW6.NTF), which contains forms that track discussion
threads in a hierarchy, as well as views that display the entries by date, author, or category. Designer
templates have NTF as their file extension.

See the appendix ″Domino Designer Templates″ for a list of common Designer templates.

31
Customizing a template
The templates that ship with Designer are master templates by default. This means that changes made to
a master template are passed along to all databases created from that template. Inheriting design changes
from a master template can be initiated by the end user or by the Domino server, which runs a nightly
Designer task. You can disable this feature by deselecting ″Inherit design from master template″ on the
Design tab of the Database Properties box.

For more information on customizing a template, see the topic ″Creating templates″ in the chapter
″Completing an Application and Managing Design Changes.″

To create a new database from a template


After creating a database from a template, you may want to make changes to the database. Keep in mind
that if you have selected ″Inherit design from master template,″ changes you make to a database can be
overwritten nightly by the Domino server Designer task or by refreshing the design of the database. If
you plan to make design changes to the database and want to avoid the possibility of writing over design
changes, deselect the database property ″Inherit design from template″ or protect individual design
elements.
1. Choose File - Database - New. In the Server field do one of the following:
v Keep Local selected to store the new database on your hard disk.
v Select or enter a server name to store the new database on a server. This allows multiple people to
work on the database design.
2. In the Title field, enter a title for the new database, using a maximum of 96 characters.

Note: As you type, Designer adds the title to the File Name field. You can accept this database file
name or change it, as follows:
v File names can be any number of characters long (within the limits of your operating system).
v File names must end with the NSF file extension.
v If you plan to use the database you are creating as a template, use the NTF file extension instead of
NSF.
3. Select a template from the list. To display additional templates, do one of the following:
v Click ″Show advanced templates″ and select a template from the list.
v Click ″Template Server″ to use templates that reside on a server.
4. (Optional) Click Encryption. Select ″Locally encrypt this database using,″ select an encryption type,
and then click OK. For information on encrypting a database, see the topic ″Notes and Domino
encryption″ in the chapter ″Security in an Application.″
5. (Optional) If you are developing an application for use with Lotus Notes and Domino Release 4.x or
if you will be on a Domino 4.x server, click ″Size limit″ and select a size (in gigabytes).
6. (Optional) Click Advanced and select the options that you want applied to your database.
For a description of the advanced options, see the topic ″To set database properties that optimize
database performance″ in the chapter ″Optimizing and Troubleshooting Databases.″
7. Click OK.
8. (Optional) Choose File - Database - Properties, click the Design tab and deselect ″Inherit design from
template.″ This prevents the new database from inheriting design changes from the master template
whose design the database is based on.

Copying an existing Domino database


If you have found an application that contains all or most of the functionality you are looking for, you
can:
v Copy the design of the database and use it as the basis for a new application.
v Copy individual design elements.

32 Application Development with Domino Designer 7


You can use the database as is, or you can modify it. If you modify a database, be sure to protect the
individual design elements from being overwritten by a design refresh or replace.

To create a new database by copying an existing database


Before you copy the design of a database, check its Database Properties. If ″No design information
available″ is shown on the Design tab of the Database Properties box, the designer has hidden the design
of the database, and you will not be able to modify the design of the new database.

If you copy the design of an existing database, keep in mind that the settings for the full-text index are
copied as part of the design. When you complete the new application, be sure to ask the database
manager to create a new full-text index.

For information on creating a full-text index for a database copy, see Administering the Domino System.
1. Open the database you want to copy.
2. Choose File - Database - New Copy.
3. In the Server field do one of the following:
v Leave Local selected to store the new database on your workstation hard disk.
v Select or enter a server name to store the new database on a server. This allows multiple people to
work on the database design.
4. (Optional) In the Title field, enter a title for the new database. The title can have a maximum of 96
characters.

Note: When you copy a database, Designer automatically gives the new database the same title and
file name as the original database. You can accept the database title and file name or change it.
Database file names can be any number of characters long (within the limits of your operating
system), and must end with the NSF file extension. If you plan to use the database you are creating
as a template, use the file extension NTF rather than NSF.
5. (Optional) Click Encryption, select ″Locally encrypt this database using:″ and select an encryption
type. For information on encrypting a database, see the topic ″Notes and Domino encryption″ in the
chapter ″Security in an Application.″
6. (Optional) If you are developing an application for use with Lotus Notes and Domino 4.x or will be
on a Domino 4.x server, click ″Size Limit″ and select a size (in gigabytes).
7. Select ″Database design only″ so that the database’s documents will not be copied to your new
database.
8. Deselect Access Control List so that the original database’s access control list will not be copied to
your new database.
9. Click OK.
10. (Optional) Choose File - Database - Properties, click the Design tab, and deselect ″Inherit design from
template.″ This will prevent the new database from inheriting design changes from the template
whose design the database is based on.

To copy individual design elements


In addition to copying the entire design of a database, you can copy individual design elements. If there
is a form, view, or other design element you would like in your database, copy it from the original
database or template and paste it into your database.
1. Open the database or template containing the design element you want to copy.
2. From the Work pane, select the element or elements that you want to copy, such as a form or a view,
and choose Edit - Copy.
To select multiple elements, hold down the CTRL key while you are selecting the elements you want
to copy.
3. Open the database where you want to paste the element or elements.

Chapter 3. Creating an application 33


4. In the Design pane, click the type of element you are pasting, such as forms or views, and choose Edit
- Paste.

If your database inherits its design from a template, you should protect views, forms, subforms,
navigators, shared fields, or agents that you copy into your database.

For another way to copy design elements, see the topic ″Copying a design element to a new location″
later in this chapter.

To protect individual design elements


If your database inherits its design from a template, you can protect views, forms, subforms, pages,
framesets, and other design elements.
1. Select each design element in the Work pane.
2. Choose Design - Design Properties.
3. On the Design tab select ″Prohibit design refresh or replace to modify.″

If you use a template to refresh or replace the database design, to ensure that this option takes effect,
select this option as well as the option ″Propagate this prohibition of design change″ in the design
properties of the template.

For additional information on protecting design elements, see the topic ″Preventing design changes″ in
the chapter ″Completing an Application and Managing Design Changes.″

Starting a database from scratch


If you need a unique application, start from scratch. To do this, begin by creating a blank database, based
on the -Blank- template. A blank database contains no design elements such as pages or forms. Blank
databases have one default view. You must create all of the elements you need for the application.
1. Choose File - Database - New.
2. In the Server field do one of the following:
v Leave Local selected to store the new database on your computer.
v Select or enter a server name to store the new database on a server. This allows multiple people to
work on the database design.
3. In the Title field, enter a title for the new database. The title can have a maximum of 96 characters.

Note: As you type a title, Designer adds the name to the File Name field. You can accept this
database file name or change it. Database file names can be any number of characters long (within the
limits of your operating system). If you want the database to appear in the Database Open dialog box,
it must end with the file extension NSF. If you plan to use the database you are creating as a
template, use the file extension NTF rather than NSF. For more information about creating templates,
see the topic ″Creating templates″ in the chapter ″Completing an Application and Managing Design
Changes.″
4. (Optional) Click Encryption, select ″Locally encrypt this database using,″ and select an encryption
type. For information on encrypting a database, see the topic ″Notes and Domino encryption″ in the
chapter ″Security in an Application.″
5. (Optional) If you are developing an application for use with Lotus Notes and Domino 4.x or if the
application will be on a Domino 4.x server, click ″Size Limit″ and select a size (in gigabytes).
6. Select -Blank- as the template.
7. Click OK.

You are now ready to begin creating the design elements for your application.

34 Application Development with Domino Designer 7


Organizing your application
Bookmarks and folders allow you to organize your work according to your needs, and to easily
reorganize your work as your design progresses. Create bookmarks that link to applications and
databases that you frequently use. Create folders to contain bookmarks, databases, design elements, and
even other folders.

Working with the Bookmark bar, you can organize databases and applications in the following ways:
v Bookmark a database or application
v Copy a design element to a new location or to a new database
v Create a folder for bookmarks or design elements

Creating a bookmark on the Bookmark bar


You can create bookmarks from the Designer menu or by using drag and drop.

To create a bookmark using drag and drop


For easy access to application and databases you use frequently, you can drag and drop these items to
the Bookmark bar or to a folder on the Bookmark bar:
v An application shortcut from your desktop
v A program executable file from Windows Explorer
v A database icon from the Design pane
v A database Window tab

To create a database bookmark from the Designer menu bar


1. Choose File - Database - Open.
2. Select the database you want to bookmark.
3. Click Bookmark.
4. Do one of the following in the ″Add to″ dialog box:
v To display the bookmark directly on the Bookmark bar, select -Bookmark Bar-.
v To add the bookmark to a folder on the Bookmark bar, select a folder.
v To create a new folder, click ″New folder,″ type a name for the folder, and click OK.
5. Click OK. You can access the database by clicking the icon on the Bookmark bar or folder.

To manage your bookmarks and bookmark folders


Once you’ve created your bookmarks, you can work with them in the following ways:

To Do this
Remove a bookmark or bookmark folder Right-click on the bookmark or bookmark folder and
select ″Remove Bookmark″ or ″Remove Folder.″
Note: When you remove a bookmark folder, you also
remove all of the bookmarks in the folder.
Rename a bookmark or bookmark folder 1. Right-click on the bookmark or bookmark folder and
select ″Rename Bookmark″ or ″Rename Folder.″
2. Type the new name for the bookmark or bookmark
folder.
Change the bookmark icon size on the Bookmark bar 1. Choose File - Preferences - User Preferences.
2. Click Basics.
3. Under Display Options, choose a size from the
″Bookmark icon size″ list.
4. Restart Designer to see your changes.

Chapter 3. Creating an application 35


To Do this
Change the bookmark icon color scheme on the 1. Choose File - Preferences - User Preferences.
Bookmark bar
2. Click Basics.
3. Under Display Options, choose a color scheme in the
″Icon color scheme″ list.
4. Restart Designer to see your changes.
Change a bookmark icon or a Bookmark folder icon 1. Right-click on the bookmark or bookmark folder and
select ″Change Bookmark Icon″ or Change Folder
Icon.″
2. Select an icon from the list of available options in the
″Insert Image Resource″ dialog box.

Copying a design element to a new location


Using the drag and drop feature in Designer, you can copy a design element into a folder or another
database.

To copy a design element to a database folder


1. Click a design element icon to expand the design element list.
2. From the expanded design element list, drag a design element to a database folder.
--or--
Drag the design element Window tab to a database folder.

To copy a design element from one database to another


1. Click a design element icon to expand the design element list.
2. From the expanded design element list, drag a design element into the design element list in another
database.

Creating folders for bookmarks or design elements


To organize your design work, you can create the following:
v A folder on the Bookmark bar for easy access to items that you use frequently such as applications,
databases.
v A folder within a folder on the Bookmark bar
v A folder in a database as a way of organizing and structuring the design elements in your database.
v A folder within a folder in a database

To create a folder on the Bookmark bar


1. In the Design pane, click the folder icon. If the Design pane is not open, right-click the Recent
Databases folder on the Bookmark bar and select Create New Folder.
2. In the Folder name text box, type a folder name.
3. In the Create Folder dialog box, select the -Folders- location and click OK.
The folder appears on the Bookmark bar. If you move the cursor over the folder, its name appears as
pop-up text. You can now populate this folder with applications, databases, and other folders.

To create a folder within a folder on the Bookmark bar


1. Right-click the folder.
2. Select ″Create New Folder.″
3. In the Folder name text box, type a folder name.
4. In the ″Select a location for the new folder″ list box, select the folder in which you want to create the
folder and click OK.

36 Application Development with Domino Designer 7


When you click the containing folder on the Bookmark bar, the new folder appears in the Design
pane. You can now populate this folder with applications and databases.

To create a folder in a database


1. Create a bookmark to a database on the Bookmark bar or in a folder on the Bookmark bar.
2. In the Design pane, click the folder icon. If the Design pane is not open, right-click the Recent
Databases folder on the Bookmark bar and select ″Create New Folder.″
3. In the Folder name text box, type a folder name.
4. In the ″Select a location for the new folder″ list box, select the database in which you want to create
the folder and click OK.
Designer places the folder at the end of the database design element list. You can now populate this
folder with design elements and other folders.

To create a folder within a folder in a database


1. Right-click the folder.
2. Select ″Create New Folder.″
3. In the Folder name text box, type a folder name.
4. In the ″Select a location for the new folder″ list box, select the folder in which you want to create the
folder and click OK.
The new folder appears in the database folder. You can now populate this folder with design elements
and other folders.

Using toolbars
Toolbars contain icon buttons that when clicked perform simple actions like printing a document or
opening a database. Toolbars give you a quick alternative to looking through a series of menus to initiate
an action. Notes provides a number of pre-defined toolbars that contain a set of icon buttons for specific
tasks, as well as the capability to create your own.

For more information on toolbars, see the topic ″Toolbars″ in Lotus Notes Help. If Lotus Notes Help is
not installed, go to http://www.lotus.com/ldd/doc to download or view the Help.

For information on creating toolbar buttons to run custom formulas, see the topic ″Toolbars″ in the
Domino Designer Programming Guide.

Enabling subscriptions
Subscriptions work in conjunction with the Headlines database. The Headlines database enables users to
stay informed of current events both within their company and on the Web by subscribing to databases
that are of interest to them and then receiving notification when a posting meets their subscription
profile.

When you design a database you can enable it to for subscriptions, consider the following:
v The database must reside on a server that allows subscription monitoring. The Domino administrator
must enable subscriptions in the Server document. See Administering the Domino System for more
information on enabling subscriptions at the server level.
v The database must enable headline monitoring. This is enabled by default on the Advanced tab of the
Database Properties box. For more information on performance and headline monitoring, see the topic
″Properties that improve database performance″ in the chapter ″Optimizing and troubleshooting
databases.″
v The database must have a default view specified. For more information on specifying a default view,
see the topic ″Default views″ in the chapter ″Designing Views.″

Chapter 3. Creating an application 37


v (Optional) The database can contain a subscription form. You can design one yourself or copy the
subscription form from the HEADLINES.NSF database in the Notes client. To copy the subscription
form from the headlines database to your database, see the topic ″To copy an individual design
element″ earlier in this chapter. If you are creating a new subscription form, you must use a formula
field. For more information on formula fields, see the topic ″Formula fields″ in the chapter ″Designing
Fields.″

Reducing database maintenance with shared code and shared


resources
You can designate many items, such as graphics, fields, subforms, and even programs, as shared
resources. Sharing resources lets you reference a resource repeatedly throughout an application, while
only having to maintain in one standard place. For example, if you use your company logo in many
places throughout your application and the design of your logo changes, you need only change it once
and the change will be implemented everywhere that image is referenced. Each database can contain its
own library of shared code and shared resources, and you can access shared elements in other databases

You can create the following resources:


v Image resources
Image resources are graphic files that can be used throughout your application. While image resources
can be GIF, JPEG, or BMP format, they are saved in Designer as GIF or JPEG. An image resource can
be used as a graphic or icon on pages, forms, subforms, action buttons, outline entries, and as
background images on forms, documents, pages, table cells, and action buttons. For more information,
see the topic ″Creating an image resource″ later in this chapter.
v Shared Fields
You can define a field for use on more than one form. For example, many forms have a creation date
field; you can define this field once and reuse it. When you define a field as a shared field, Designer
displays the field with a dark border and adds the field name to a list of shared fields available for use
in a database. For more information, see the topic ″Creating shared fields″ in the chapter ″Designing
Fields.″
v Non-NSF file resources
You can share non-NSF files within and across databases. For more information, see the topic ″Sharing
file resources″ later in this chapter.
v Subforms
A subform is a collection of fields, graphics, buttons, and actions you plan to use in more than one
form. For example, you might create a corporate letterhead in a subform and then use the subform on
a variety of business forms. For more information, see the topic ″Subforms″ in the chapter ″Designing
Forms.″
v Script libraries
A script library is a place for storing code that can be shared in the current application using
LotusScript, JavaScript, and Java or in other applications using JavaScript and Java. Using script
libraries allows you to maintain code in one place. For more information about script libraries, see
″Using script libraries″ in the Domino Designer Programming Guide.
v Shared Java files
For large Java applets with multiple files, it is most efficient to store some of the related files as shared
resources in the database. When you set up files as shared resources, all the applets can use a single
copy of the file, instead of each applet storing its own copy. Then, if a file requires updating, you only
need to update one file. For more information, see the topic ″Setting up shared applet resources″ in the
chapter ″Including Java Applets in Applications.″
v Shared actions
Use shared actions in forms, pages, folders, or views to set up user-activated tasks. You can add shared
actions to the Actions menu or as buttons on the action bar. In particular, actions let users complete

38 Application Development with Domino Designer 7


tasks when accessing Domino databases on the Web. For more information on shared actions, see the
topic ″Creating and inserting shared actions″ in the chapter ″Adding Automation to Applications.″
v Cascading style sheets
You can browse your local file system for a cascading style sheet (CSS) and insert one into a page,
form, or subform. For more information, see the topic ″Creating style sheets as shared resources″ in the
chapter ″Designing Pages.″

Sharing file resources


Designer allows you to share non-NSF files within and across databases. This capability gives you greater
flexibility in designing your application. For example, you might need to reference a shared company
logo that is a GIF file, or all applications in your company might share a welcome page that is an HTML
file, created by and maintained in a tool other than Lotus Notes or Domino Designer. To share these files,
you must designate them as file resources.
v Create a file resource
v Open a file resource
v Refresh a file resource
v Prevent a file resource from being refreshed
v Export a file resource
v Delete a file resource
v Deploy a file resource to the Web

To create a file resource


1. On the Design pane, click ″Shared Resources.″
2. Click Files. The files work pane opens.
3. Click ″New File Resource.″
4. Select the file you want to designate as a shared resource. You can also select multiple files.
In the Open dialog box, click ″Open″ to add the files to the work pane as shared resources in the
database.
5. Choose Resource - Resource Properties. At the Basics tab, you can assign the following file resource
properties:
v Name
The name of the file resource (for example, welcome.html). Each file resource in a database should
have a unique name.
v Alias
A file resource can have additional names (aliases). Using aliases lets you change the file resource
name without having to rewrite every formula that references a file resource name.
v Comment
Additional information that is helpful in identifying the file resource.
v Needs refresh

To open a file resource


1. In the files work pane, highlight the file resource that you want to open.
2. Do one of the following:
v Click ″Open File″ to let Designer select an application to open the file resource.
v Click ″Open With″ and then select an application to open the file resource.

You can now edit the file.

Chapter 3. Creating an application 39


To refresh a file resource
To save changes to a file resource you have edited, you must refresh it. A file resource that has been
edited but not yet refreshed is identified in two places:
v In the files work pane, the filename is preceded by a refresh icon
v In the File Resource properties box, the ″Needs refresh″ check box is selected.
1. In the files work pane, highlight the file resource that you have edited.
2. Click Refresh.
3. In the Open dialog box, select the updated file name (it appears preceded by a tilde (~)), and click
Open.
The file resource is refreshed. The refresh icon disappears from the files work pane and the ″Needs
refresh″ check box in the File Resource properties box is cleared.

To prevent a file resource from being refreshed


When you have edited a file resource and do not want to save the changes, do not refresh it. You can
identify a file resource that has been edited but not yet refreshed in two ways:
v In the files work pane, the filename is preceded by a refresh icon.
v In the File Resource properties box, the ″Needs refresh″ check box is selected.

To prevent a file resource from being refreshed:


1. In the files work pane, highlight the file resource that you have edited.
2. In the File Resource properties box, clear the ″Needs refresh″ check box.
The file resource is not refreshed and the refresh icon disappears from the files work pane.

To copy a file resource to your computer


To save a copy of a file resource on your computer, you can export a copy.
1. In the files work pane, highlight the file resource that you want to export.
2. Click Export.
3. In the Save As dialog box, select a location for the file resource in your directory structure. The file is
saved in the location that you specified.

To delete a file resource


Delete a file if you no longer want to include it as a shared resource.
1. In the files work pane, highlight the file resource that you want to delete. You can also select multiple
delete files at one time.
2. Press DELETE. The files are removed as shared resources and no longer appear in the files work
pane.

To set up a file resource for use on the Web


If you plan to use your file resource on the Web, click the following fields on the Web Properties tab to
set up the file resource appropriately.
v Read Only - checking this causes the selected design element(s) to be read only on the Web.
v MIME type - the MIME type of the file resource for Web clients. The Content-Type header of the HTTP
response is set to this value. Domino Designer fills in this field if it recognizes the extension of the file
resource (for example, a GIF image file or an EXE application file).

40 Application Development with Domino Designer 7


Creating an image resource
You can create a resource library of images to use throughout your database. Image resources let you
maintain the image in only one location. If there are any changes to the image, changing and refreshing
the source file distributes the changes wherever the image is referenced.

To create a shared image resource


1. Expand ″Shared Resources″ in the Design pane.
2. Select Images from the list of Resources.
3. Click ″New Image Resource.″
4. Select GIF, BMP or JPG in the ″Files of type″ list.
5. Select one or more graphic files you want to include as image resources.
6. Click ″Open.″ The graphic files you selected are added to the list of image resources.

To set image resource properties


To open the Image Resource Properties box, select the image from the list of images and choose Resource
- Resource Properties.

Basics tab
On the Basics tab, the name of the image appears automatically. You can also provide an alias and a
comment, both of which appear next to the image resource name in the list of images.

You can also specify:


v Images across and Images down (if you are creating image sets).
v Colorize grays - lets an image blend with the user’s system colors.
v Needs refresh - adds the refresh symbol next to the image resource name in the list of images and
targets it as an image to be refreshed.
v Web browser compatible - appears if you are creating a horizontal image set (Images down) and want
the images to work on the Web.

Design tab
On the Design tab of the Image Resource Properties box, select any of the following design options:

Field or box Description


Inherit from the design template Type the name of a template from which the design
element might inherit changes.
Prohibit design refresh or replace to modify Select this to prevent this design element from being
modified during a refresh or replace.

If you use a template to refresh or replace the database


design, to ensure that this option takes effect, select this
option as well as the option ″Propagate this prohibition
of design change″ in the design properties of the
template.
Propagate this prohibition of design change Select this so that if a database inherits this design
element, the ″Prohibit design refresh or Replace to
modify″ box option will be inherited also, and it will still
be selected.
Hide design elements from (Web Browsers) Select to hide the design element from Web users.
Hide design elements from (Notes R4.6 or later clients) Select to hide the design element from Release 4.6 or
later clients.

Chapter 3. Creating an application 41


To colorize grays
If you want an image to blend with the user’s system colors, select the option ″Colorize grays″ on the
Basics tab of the Image Resource Properties box. When enabled, the grays in an image that use the Lotus
palette change to the color scheme of the user’s operating system. This feature lets the image resources
blend in with the other elements of the user’s system, such as dialog boxes and menu bars.

To insert an image resource


1. Open a form, document, or page.
2. Place the cursor where you want to add the image.
3. Choose Create - Insert Resource.
4. Under Databases, select the database from which you want to insert the image resource.
5. Under ″Resource type,″ select Images.
6. Under ″Additional resources,″ select an image to insert from the list of images.
7. Click OK to display the image in the form, document, or page.

Tip: You can use the images among multiple databases by putting the image into a template. Databases
inheriting from that template have easy access to the image.

For more information on creating templates and inheriting design, see the topic ″Templates″ in the
chapter ″Completing an Application and Managing Design Changes.″

To insert an image resource from a file in the current database


You can insert an image resource from a file that you created and stored in your current database.
1. Open a form, document, or page.
2. Place the cursor where you want to add the image.
3. Choose Create - Image Resource.
4. In the ″Insert Image Resource″ dialog box, make sure that the Database is set to -Current database-.
5. Click ″New.″
Browse your directory to include an image resource in the current database.
6. After you have selected a file, in the Insert Image Resource dialog box, click OK.
The image resource appears in the form, document, or page.

To rename an image resource


Perform the following steps to rename an image resource that you created.
1. Open a form, document, or page.
2. Choose Create - Image Resource.
3. In the Insert Image Resource box, select the image resource that you want to rename.
4. Click Rename.
5. Type a new image resource name. You should also specify an alias if there is a chance that the image
resource could be renamed. To specify an alias, after the image resource name, type a vertical bar (|)
followed by the alias name. For example, ImageName|ImageAlias.
The new name appears in the image resource list.

To delete an image resource


Perform the following steps to delete an image resource that you created.
1. Open a form, document, or page.

42 Application Development with Domino Designer 7


2. Choose Create - Image Resource.
3. In the Insert Image Resource box, select the image resource that you want to delete.
4. Click Delete. The image resource is deleted from the image resource list and from the database.

To reference an image resource with HTML


You can use Pass-thru HTML to reference image resources within a database.
1. Enter the HTML <img src> tag using the name of the image resource. For example:
<img src="r5-banner.gif">
2. Select text and choose Text - Pass-thru HTML.
3. (Optional) Use other HTML formatting tags to position the image.

To make design changes to an image resource


To make design changes to a graphic used as an image resource, export the image to a graphics program.
Once the changes are made, update the image resource and distribute the design changes.

Exporting an image resource


1. Select the image or images you want to redesign.
2. Choose Resource - Export.
3. Select the directory you want to copy the image to.
4. Click Open.

Distributing design changes for an image


When you redesign an image resource, you can distribute the changes wherever the image appears in the
database.
1. In the list of images in Designer, select the images that have changed and click Refresh.
2. In the Open dialog box, select the images from your directory.
3. Click ″Open.″

Designer automatically updates the image in all of the places it is referenced in the application.

Creating a custom letterhead


You can select a graphic to appear as the mail header for all employee mail. Simply add your company’s
logo to the image resources of your organizations’ mail templates. Only employees who have access to
the mail template will see the letterhead; other recipients, such as those outside your company or with an
Internet mail account, will receive a standard letterhead.

For details on creating a custom letterhead, see ″Creating a custom letterhead″ on the Lotus Developer
Domain.

Creating image resource sets


There are two types of image resource sets: horizontal and vertical.

Use a horizontal image set to create an image that appears to change depending on its state. For example,
when a user passes the mouse over an image you might want it to appear to light up. To effect this,
create a second image in the set and adjust the background color of the graphic. You may also want the
image to appear to get darker as the user clicks on it, and dimmer once it has been clicked.

Use a vertical image set for icons you are adding to the bookmark bar on the Notes, Designer, and
Administration client. The bookmark bar can display small, medium, or large icons provided that the

Chapter 3. Creating an application 43


image resources for those icons are part of a vertical image set. A vertical image set includes an icon in
three different sizes. To set the size for icons on the bookmark bar, users choose File - User Preferences.
At the ″Bookmark icon size″ setting on the Basics page, they can choose Small, Medium, or Large.

To create a horizontal image set


1. In a graphics program, copy and modify an image to create a series of images in different states.
All of the images must be the same size.
2. In a single GIF, BMP, or JPG file, line up the images horizontally and separate them with a
one-pixel-wide well or line.
3. Create an image resource from the graphic file.
4. Double-click the image resource in the list of image resources in the Work pane.
5. On the Basics tab of the Image Resource Properties box, enter the number of images across in ″Images
Across.″
The number of images corresponds to the number of states you are using. The four images map to the
four states as follows:

Images across property to select State Position of image used


1 Normal image First position
2 Mouse-over image Second position
3 Selected image Third position
4 Mouse-down image Fourth position

Note: The order of the states is predetermined and cannot be changed. However, if you want to take
advantage of only two of the states, for example, if you want to use a different image in the normal
state (the first position) only, copy the second image two or three times so that the different image is
in the first position.

To create a vertical image set


To create a vertical image set:
1. In a graphics program, copy and modify an image to create a series of images in different states.
All of the images must be the same size.
2. In a single GIF, BMP, or JPG file, line up the images vertically, with a one-pixel-wide well between
each one.
3. Create an image resource from the graphic file.
4. Double-click the image resource in the list of image resources in the Work pane.
5. On the Basics tab of the Image Resource Properties box, enter the number of images down in ″Images
Down.″
6. Create a rectangle background around the images to create a rectangle.

44 Application Development with Domino Designer 7


To use the image set on the Web
When you are using a horizontal image set in a Web application, select the option ″Web browser
compatible″ on the Basics tab of the Image Resource Properties box. The ″Web browser compatible″
option appears only when the number of images across (entered on the Basics tab of the Image Resource
Properties box) is greater than 1.

If you are not using multiple images in a Web application, deselect this option to save space in your
application.

Document locking
When you set the database property ″Allow document locking,″ users with Author access or higher can
lock documents in that database. Locking a document prevents editing and replication conflicts by
ensuring that person who locks the document has exclusive rights to modify the document; others with
the same rights cannot modify a locked document even if they are working on a different replica on the
same LAN. Managers of a database cannot edit a locked document. However, managers can unlock
documents that are locked.

For information on how users lock a document, see the topic ″Locking Documents″ in Lotus Notes Help.
Or, go to http://www.lotus.com/ldd/doc to download or view Lotus Notes Help.

To allow document locking


1. Specify an administration server for the database. This server will be used as the master lock server
when a user locks a document.
2. Choose File - Database - Properties and click the Basics tab.
3. Select ″Allow document locking.″

To prevent document locking


1. Choose File - Database - Properties and click the Basics tab.
2. Deselect ″Allow document locking.″

Customizing twisties
The triangular icons that indicate a row or a section may be expanded or collapsed are called ″twisties.″
Twisties are green in Notes and blue on the Web. You can customize these icons by importing your own
images. You import two images into one graphics file. The first image replaces the ″expand″ twistie and
the second replace the ″collapse″ twistie. A pair of images for customized twisties should result in a .gif
file that is 33 x 16 pixels -- that is, two 16 x 16 images, with a 1-pixel divider.

Chapter 3. Creating an application 45


1. Using a graphics program, create an image well by importing two images into one graphic. One of
the images will appear as the icon that expands a row or section, and the other will appear as the
icon that collapses the row or section. Place the expand image on the left and the collapse image on
the right.
2. In Designer, create an image resource from the icon file.
3. In the Image Resource work pane, double-click the image resource to open the Image Resources
Properties box:
v Enter ″2″ next to ″Images across.″
v Check ″Web browser compatible.″
4. In the View work pane, select the expandable column and open the Column Properties box. At the
Column Info tab:
v Check ″Show twistie when row is expandable.″
v Enter the name of the image resource file you just created in the ″Twistie Image″ setting. Click the
folder button to browse for the image file.

Previewing your design work


To see how your application looks and behaves on the Notes client and on the Web, you can preview
your work in Notes and in supported browsers. When you start up your computer, Designer searches for
the following browsers:
v Internet Explorer
v Netscape

For each supported browser Designer finds, it adds an icon to the Preview tool bar. If you have both
Netscape version 3.x and 4.x both icons appear. The toolbar also displays icons for previewing the
application through the Notes browser and the Notes client. Note that previewing in Notes serves the
application through the Domino server, while previewing in Notes serves the application directly to the
Notes client.

Clicking a browser icon previews the current design element -- that is, the page, form, or navigator you
are designing -- in the associated browser.

You can also preview elements from the Design list. For example, you do not need to open up a form to
preview it; you can select it in the list of forms and click one of the preview icons.

To preview in Notes or in the default Web browser using the menu


1. Open the design element you want to preview or select it from the Design list.
2. Make design changes if necessary.
3. Choose Design - Preview in Notes or Preview in Web browser <Web browser>. You will be prompted
to save any changes. If you do not save your changes, Designer will preview your work without the
changes.
4. (Optional) To stop the Web browser preview without exiting Notes, choose File - Tools - Stop Local
Web Preview Process.

To preview in Notes or in the default Web browser using the preview


icons
1. Open the design element you want to preview or select it from the Design list.
2. Make design changes if necessary.
3. Click the icon on the Menu bar for the browser you want to use. You are prompted to save any
changes. If you do not save your changes, Designer displays your work without the changes.

46 Application Development with Domino Designer 7


4. (Optional) To stop the Web browser preview without exiting Notes, choose File - Tools - Stop Local
Web Preview Process.

To set up a default browser for previewing


To set up previewing, you must override the proxy settings so the preview process can find the databases
-- both on your local machine and on any servers that have databases you need to preview.
1. In Designer, choose File - Preferences - Location Preferences.
2. Next to Proxy, click the Advanced icon.
3. Next to ″No proxy for these domains,″ add these case-sensitive entries:
localhost
<Domino server name>
4. Click OK.
5. Close and save the Location document.

To override proxy settings for additional browsers


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

Requirements for previewing your design work on the Web


v You must be using Windows 95, Windows 98, Windows 2000, Windows XP, or NT workstation.
v You must modify the application’s access control list. The Web preview process uses the access
assigned to -Default- or, if available, an entry called Anonymous. One of those entries needs Reader
access to let you preview pages, framesets, documents, navigators, and views. One of those entries
needs Author access with create document permission to let you preview forms.
v 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.
v The element to be previewed must not be marked as hidden from Web browsers.
v Your browser(s) must be set up to override proxy settings (described below).

Adding instant messaging to an application


Some Notes applications, such as mail or discussion applications, can benefit from instant message
services that allow users who are online at the same time to communicate directly with each other. You
can integrate IBM Lotus Instant Messaging in an application to provide this capability. For an example of
how instant messaging works in an application, see the Lotus Notes mail template. In order for users to
use the instant messaging feature, they must be connected to a Lotus Instant Messaging server through
their Notes location document.

You can integrate online awareness in forms or views. For example, in the Notes mail application, you
can see the online status of users listed in the From, To, and CC fields of a mail document. If a user is
active, you can click a name and initiate a chat. In the Inbox folder of the Mail template you can see the
online status for mail senders who are Lotus Instant Messaging users. You can also embed a Lotus Instant
Messaging Contact List in a page or form. A user opening the page or form will see their contact list.

Note: This feature is not available for Web applications.

Chapter 3. Creating an application 47


For information on enabling online awareness for Names fields, see Enabling a field for instant
messaging.

For information on enabling online awareness for views, see Enabling a column for instant messaging.

For information on embedding a contact lists, see Embedding an Instant Messaging Contact List

Preventing users from accessing forms and views in a Web


application
As you design an application users will access with a browser, you may want to restrict browser users
from using URL commands that would open forms and views in your application. For example, you can
design your application so that a servlet that uses forms or views will only use the forms and views
using URL commands. With the ″Don’t allow URL open″ property set, it will be impossible for browser
users to manipulate these application components using Domino URL commands.

To restrict users from opening parts of an application using URL


commands
1. Select a database and choose Design - Design properties.
2. In the Web Access section of the Database properties box, select ″Don’t allow URL open.″

The set of URLs that gets restricted is http://Host/Database.nsf/*Command. This set of URLs includes
any command that will open a database such as http://Host/Database.nsf and all URL commands that
are prefixed with a ?, such as http://host/database.nsf?OpenDatabase. When this property is set, the
error displayed is:

Error 500

HTTP Web Server Lotus Notes Exception - You are not authorized to access that database.

48 Application Development with Domino Designer 7


Chapter 4. Designing pages
Pages and forms are similar in certain ways. A page is a database design element that displays
information. Pages can be used anywhere in your application that you have text, graphics, or an
embedded control, such as an outline, to present to the user. A page or form can contain the following:

Elements to use on a page Description


Actions Actions automate tasks for the user. Add actions to the menu in the Notes client,
or add actions with buttons or hotspots on a page or form. For more information,
see the topic Actions

in the chapter ″Adding Automation to Applications.″


Applets Use Java applets to include small programs, such as an animated logo or a
self-contained application, in a page or form. For more information about
including Java applets on a page or form, see the chapter ″Including Java Applets
in Applications.″
Attachments Attach files to a page or form so users can detach or launch files locally.
Computed text Use computed text to generate dynamic text based on formula results.
Embedded elements You can embed the following elements in a page or form: a view or folder pane,
navigator, outline, date picker, or Instant Messaging Contact List. Use these
elements alone or combine them to control how users navigate through your
application.
Graphics Place a graphic anywhere on a page or form. Use graphics to add color to a page
or form or to create imagemaps.
Horizontal rules Add horizontal rules to separate different parts of a page or form, or to make a
page or form more interesting visually.
HTML If you have existing HTML or you prefer using HTML to using the formatting
tools Designer offers, you can import, paste, or write your own HTML on a page
or form. You can also convert pages and forms to HTML.
Imagemaps An imagemap is a graphic you enhance with programmable hotspots. Hotspots, in
the form of pop-up text, actions, links, and formulas, perform an action when
clicked by a user. Use imagemaps as navigational structures in an application.
JavaScript libraries You can find and insert JavaScript libraries into a page, form or subform. For more
information on inserting JavaScript libraries, see the topic ″Inserting a JavaScript
library″ in this chapter.
Layers Layers let you position overlapping blocks of content on a page, form, or subform.
Layers give you greater design flexibility because you can control the placement,
size, and content of information. For more information on layers, see the topic
″Layers″ in this chapter.
Links Add links to take users to other pages, views, databases, or URLs when they click
on text or a graphic.
OLE objects and custom Designer supports objects that are linked and embedded (OLE) as well as custom
controls controls, sometimes called OCX controls. Including a linked or embedded object
on a page or form lets you use a page or form as a gateway to another
application. For example, an Employee Information page or form can include an
OLE object that links to a Word Pro® file where the employee annual performance
reviews are stored. Notes/FXTM 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. For more information on including OLE objects
and custom controls on a form, see the chapter ″Including OLE Objects in
Applications.″

49
Elements to use on a page Description
Sections A section is a collapsible and expandable area that can include objects, text, and
graphics.
Style Sheet (CSS) shared You can find and insert a cascading style sheet (CSS) as a shared resource on a
resources page, form, or subform. For more information on style sheets, see the topic
″Creating style sheets as shared resources″ in this chapter.
Tables Use tables to summarize information, align text and graphics in rows and
columns, or position elements on a page or form. For more information on
creating programmable tables, see the topic ″Creating programmable tables″ in this
chapter.
Text Use text anywhere on a page or form and apply text attributes, such as color, size,
and font styles to the text. For complete information on creating and formatting
text, see Notes Client Help.

For all other information on creating and formatting tables, see the topic ″Creating tables″ in the Notes
Client Help.

How pages compare to forms


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

Creating pages
A page is a design element that displays information to users. It is similar to a form except that it does
not contain fields or subforms.

To create a page
1. Click Pages in the Design pane.
2. Click ″New Page.″
3. Create the contents for the page, using elements such as text and graphics.
4. Choose Design - Page Properties to assign the following page properties:

Page Properties box


Tab Action

50 Application Development with Domino Designer 7


Page Properties box
Page Info tab v Give the page a name.
v Optionally, enter a comment.
v Check ″No Initial Focus″ if you want the page to have no focus when first opened.
v Check ″No focus on F6″ if you want to disable the F6 and Shift F6 keys, which give
focus to a frame.
v Check ″Render pass through HTML in Notes″ so the page containing the HTML
appears correctly in Notes.
v In the Web Access section, you can check one of the following for the type of content:

- Notes

- HTML

- Other - if you specify Other, enter the type of content you want.

You can also choose a character set for the Web user.
v Set the default color for links appearing on the page. You can set colors for active,
unvisited, and visited links.
Background tab Select the background color or graphic for the page.
Launch tab Select launch options for the page.
Security tab Set security options for the page.

To delete a page
1. Click Pages in the Design pane.
2. Select the page you want to delete.
3. Choose Edit - Delete.
4. Click Yes to confirm.

Displaying a page
Pages do not display in views. To work around this, you can display pages in the following ways:

Options for displaying pages For more information, see


Make the page a frame in a frameset. The chapter Designing Framesets.
Create a link to the page from a form, subform, The topic ″Creating links″ in this chapter.
outline, or another page.
Create an action that opens the page. The topic ″Actions″ in the chapter ″Adding Automation to
Applications.″
Create an outline entry that opens the page. The topic ″Outlines″ in the chapter ″Designing Navigation for
an Application.″
Set the database launch property to launch the page The topic ″Setting database launch properties″ in the chapter
when the database is opened. ″Completing an Application and Managing Design Changes.″

Chapter 4. Designing pages 51


Creating a home page for an application
A home page gives users a logical entry point to an application and provides a summary of the
information in the application. Make sure to provide links back to the home page from other places
within the site.

A home page should contain the following elements in a pleasing mix of graphics and text:
v A brief description of the company, product, service, or site
v Links that navigate to other parts of a site
v Information for new visitors
v Information for frequent visitors who need to know what is new
v A way to search for information
v If necessary, a way to register on the site to view restricted areas

Create a page with links to other pages, views, documents, or navigators in the same database or other
related databases at the site. You should take security issues into account when you decide whether to
store the home page in its own database or in a database used for other purposes, such as discussions,
user registration, or product information. You generally provide fairly open access to a home page and
limit access to other parts of a site.

For more information about security, see the chapter ″Security in an application.″

To set the home page to launch automatically


1. Choose File - Database - Properties.
2. Click the Launch tab.
3. Select the page you want to launch for Notes clients and for Web clients.
For more information, see the topic ″Setting database launch properties″ in the chapter ″Completing
an Application and Managing Design Changes.″

To specify a default home page for a Web server


A server administrator can specify a Web site’s default home page in the server document for the server.
When the administrator sets a default home page in the server document, all databases on that server
have the same default page. Contact your server administrator for more information.

Styling text for the Web


For Web applications, Domino automatically converts text styles to HTML tags when there is a
corresponding HTML equivalent. Bullets, numbers, alignment (except Full Justification and No Wrap),
spacing, and named styles are some HTML equivalents. Certain types of formatting such as indents,
interline spacing, and tabs do not appear when viewed from a Web browser because HTML has no
corresponding format. Be aware that different browsers may display tags differently and that not all
browsers support the HTML tags that Domino generates.

Fonts
If the fonts used are not the system defaults -- for example, in Windows, Default Sans Serif and Default
Serif -- Domino converts font instructions to the HTML <FONT> tag and FACE= attribute to approximate
the original font choice. Text may look different to a Web user than it does to a Notes user because the
browser determines which fonts to use.

52 Application Development with Domino Designer 7


Size
Domino maps the text size you select in Designer to an HTML text size. The following table lists the text
size in Notes and the corresponding HTML size. Note that Domino does not map font sizes to HTML
heading tags (H1, H2, and so on).

Notes text size less than or equal to Maps to HTML size


7 1
9 2
11 3 (default size)
13 4
17 5
23 6
greater than 23 7

Preserving spaces
To align a column of numbers or to preserve or insert spaces, use the default monospaced font. On a
Windows system, the default monospaced font is Courier. Domino converts the default monospaced font
to a monospaced font on the Web and preserves any spaces you enter.

Text colors
Web users see the same approximate text colors as Notes users, but the colors may not match exactly.

Creating computed text


You can use computed text to generate dynamic text based on formula results.
1. Move the cursor to where you want the computed text to appear.
2. Choose Create - Computed Text.
3. In the Programmer’s pane, click the Objects tab of the Info List and select Value (located under
Computed Text).
4. Write a formula whose value displays the text for the page.

Example: Computed text


To personalize the message a user sees on a page or form, create computed text that displays the user’s
name.

On the page or form, enter the text:


Welcome <computed text>.

Select Value (located under Computed Text on the Objects tab of the Info List).

In the Script area, enter the formula:


@Name([CN];@UserName)

If the user’s name is Sara Ryan/Acme, when she opens the page or form she will see:

Welcome Sara Ryan.

Note: Domino publishes a <span> tag around the computed text for access via JavaScript.

Chapter 4. Designing pages 53


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

Creating and formatting horizontal rules


To separate different parts of a page or form, or to make the document more interesting visually, add
horizontal rules. You can set width, height, and color (including gradient color) for horizontal rules.

To create a horizontal rule


1. Move the cursor to the place for the horizontal rule.
2. Choose Create - Horizontal Rule.

To change the style of a horizontal rule


1. Select the horizontal rule; choose Horizontal Rule - Horizontal Rule Properties.
2. Click the Horizontal Rule Info tab. On the Info tab you can:
v Change the width and height.
To change the width in inches, choose Fixed width.
To change the width as a relative percent of the window, choose Percent (%).
Note that height is always in inches.
v Select a solid color. You can select a color from the palette or customize colors by using the color
wheel button in the top right corner of the Color box. To set the color of your horizontal rule to
your system’s color scheme, click the Color box menu and click the System button.
To select a solid color, select a color and click the solid rectangle.
v Select a gradient color. A gradient color is a color that blends and fades into the other original color
within a horizontal rule. Gradient color is not supported on the Web.
To select a gradient color, select the first color, click the shaded rectangle and select the ″To″ color.
v Make a horizontal rule transparent.
Click the Color box menu and click the Transparent button.
To undo transparency, click the Color box menu and click the Undo transparent button.
v Select No 3D shading.

Creating programmable tables


There are four types of tables you can create in Designer:
v Basic tables -- Tables with a designated number of columns and rows.
v Tabbed tables -- Tables that let users switch rows by clicking on tabs at the top of the table.
v Animated tables -- Tables that switch rows at an interval you designate. Note that animated tables do
not work on the Web. Also, animated tables on forms are not designed for field entry.
v Programmable tables -- Table that switch rows based on an action or field formula.
Because creating a basic, tabbed, or animated table in Designer is the same as creating tables in the
Notes client, see the topic ″Creating tables″ in the Notes Client Help. You can also press F1 for online
help when you are creating a table.

54 Application Development with Domino Designer 7


How programmable tables work
Programmable tables let you create a table that displays one row at a time, based on an action or field
formula. A programmable table starts as a tabbed table that looks like a Designer Properties box. One tab,
or row, of the table is visible at a time to the user. With regular tabbed tables, the user clicks the tabs at
the top of the table to select which row displays. With programmable tables, the user clicks on an action,
a link, or an outline entry to select which row appears.

You write a formula in the Script area of the Programmer’s pane to control which row displays and to
associate the row with an action, link, or outline entry. Include a field in the formula that has the same
name as the name you give to the table in the Table Properties box, except precede the field name by a
dollar sign ($). Remember that table field names are case-sensitive: $table is a different table field name
than $Table.

For example, on your company’s home page, you could put a programmable table that displays different
information about your company depending on what your site visitors want to see. If they click the
″Location Information″ hot text they would see the row of the table that gives them the location of your
company. If they click the ″Company History″ hot text they see the row of the table that describes your
company’s history.

Note: When you are designing programmable tables on a form, you can use a field on the form to
control the table. You can use a choice list field that refreshes on change or use a computed field.

To create a programmable table


1. Move the cursor to where the table will appear on the page or form. In a document, you must be in
a rich-text field.
2. Choose Create - Table. The Create Table dialog box appears.
3. Select the number of rows and columns for the table.

Note: All columns in a row will appear when the row is displayed.
4. Under Table Type, click the programmable table button.
5. Click OK.
6. Choose Table - Table Properties.
7. Do the following on the Table Programming tab of the Tables Properties box:
v In the Table HTML Tags field, enter a Name/ID for the table.
v Click each row of the table and enter a name for each row in the ″Row Tags″ field.
8. (Optional) To display tabs so users can switch rows, select ″Also show tabs so user can pick row″ on
the Table Rows tab.
9. Format the table.
10. Enter text, graphics, or objects in the table.
11. Create links, a button, or an outline entry that will set the fields for the table and control what
displays.

Example: Creating hotspots to control a programmable table


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

When users click on the first hotspot they will see the text and graphics in the first row of the table only.
When they click on the second hotspot they will see the text and graphics in the second row of the table
only.

For more information about writing formulas, see the Domino Designer Programming Guide.

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

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

To format a section
1. Select the section and choose Section - Section Properties.
2. On the Section Title and Border tab, you can:
v Enter a title for the section. Titles can be either text or a formula.
Use text if the title should be the same all the time.
Use a formula if you want the title to appear differently under different conditions.
v Select the border style. The border appears around the section.
v Select a border color.
3. On the Expand/Collapse tab:
v Select options for showing the section expanded or collapsed depending on whether a document is
being previewed, opened for reading, opened for editing, or printed.
v Select ″Hide title when expanded″ if users don’t need to see the section title when the fields are
displayed.
v Select ″Show as text when not previewing″ so that the user sees the section only when the
document is being previewed. If the document is being printed or is opened for reading or editing,
the user sees the text with no visible sign that the text is contained in a section.

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

56 Application Development with Domino Designer 7


Creating links
You can create text or graphic links that users click on to navigate to other parts of an application or to
external sites on the Web. In the properties box, you can set how the link displays to users. You can use a
different color text for text links, or a hotspot around a graphic that shows when a user moves the mouse
over it. Domino converts these links to Hypertext links on the Web.

To create a Named Element link


To link to a design element, create a Named Element link. Named elements are:
v Pages
v Forms
v Framesets
v Views
v Folders
v Navigators

When you link to a named element, the link references the element’s name. Any change in the name of
the element will break the link. Whenever possible, create aliases for design elements. If the design
element has an alias, the link will be maintained as long as the alias does not change.

There are two ways to link to a named element. You can copy and paste, or you can use the Link
Properties box.

To copy and paste a link


1. Select the design element you want to link to.
2. Choose Edit - Copy as Link - Named Element.
3. Select the text or graphic that will serve as the link and choose Create - Hotspot - Link Hotspot.
The HotSpot Resource Link Properties box appears.
4. At the Hotspot Info tab, click the Paste icon.
5. (Optional) Enter a target frame for the link.
6. (Optional) Select ″Show border around hotspot.″ (Not supported on the Web.)

To create a link using the properties box


1. Select the text or graphic that you want to serve as the link.
2. Choose Create - Hotspot - Link Hotspot.
3. On the Hotspot Info tab of the Hotspot Resource Link Properties box, select Named Element as the
type of link.
4. Select the type of Named element you want to link to and do one of the following:
v Enter the name of the element.
v Click the folder icon to browse.
v Click the @ icon to enter a formula that resolves to a link.
5. (Optional) Enter a target frame for the link.
6. (Optional) Select ″Show border around hotspot.″ (Not supported on the Web.)

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


Hotspot links are more stable than traditional HTML links because they do not reference file names;
rather, they reference the unique internal ID of the element. If the name of the linked item changes, the
link remains valid.

Chapter 4. Designing pages 57


To create a link to a document, view, anchor, or database:
1. Open or select the element you want to link to. For database links, you can open the database in
either the Notes client or in Designer. For document, view, or anchor links, open or select from the
Notes client.
2. Choose Edit - Copy as Link - <type of link>.
3. Select the text or graphic that will serve as the link and choose Create - Hotspot - Link Hotspot.
The Hotspot Resource Link Properties box appears.
4. On the Hotspot Info tab, select ″Link″ for the type.
5. Click the Paste icon.
6. (Optional) Enter a target frame for the link.
7. (Optional) Select ″Show border around hotspot.″ (Not supported on the Web.)

To create a URL link


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

Using graphics
A page or form that contains a graphic is visually appealing but takes more time to display and print.
You can paste or import graphics into pages, as you can into documents, forms, views, and navigators.
Designer stores graphics in Graphics Interchange Format (GIF) and Joint Photographic Experts Group
(JPEG) in their native formats. Therefore, these are the best choices for graphic fidelity. Designer stores
other types of graphics in a platform-independent 256-color format that is similar to GIF89a format. (GIFs
are 256-color images.)

Graphics can be:


v Stand-alone graphics that add aesthetics or focus to a page or form
v Background graphics
v Imagemaps -- navigation structures composed of graphics that contain links

Preparing graphics
Your goal, when preparing a graphic, is to have it look as much as possible like the graphic you created
in your drawing program. How graphics look depends on the user’s viewer, operating system, and color
mode.
v Viewer -- Notes client or a Web browser.
– If your audience is Notes users only, use either the Lotus color palette or the Web color palette.
– If your audience is Web users only, use the Web color palette.
– If your audience is both Notes and Web users, either use black and white or very simply colored
graphics, or use the Web color palette.
v Operating system -- Macintosh, Windows NT, Windows XP Professional, Windows 95/98/2000, OS/2,
or UNIX.

58 Application Development with Domino Designer 7


Always reduce the color in graphics with formats other than GIF or JPEG to 256 or fewer colors.
Although doing this may reduce the quality of high-resolution graphics, it ensures a more reliable color
display across platforms.
v Color mode -- 16-color mode, 256-color mode, or High/True/24-bit color mode.
If all users have machines that display in true color mode, reducing the colors to 256 or fewer is all
you need to do to prepare a graphic. If users have machines running in 256-color mode, use a color
palette to map colors in the graphic to a table of predefined colors.

Changing the color palette


If you are designing applications for users to access on the Web, you can change from the Lotus color
palette to a Web color palette to provide greater color fidelity. To change palettes:
1. Choose File - Preferences - User Preferences.
2. Check ″Use Web Palette″ on the Additional Options list of the Basics tab. If this option is unchecked,
Designer uses the Lotus color palette.

Note: When Web users open a database, Domino converts non-GIF and non-JPEG graphics to GIF or
JPEG formats. The system administrator specifies the format in the ″Image conversion format″ field,
which is part of the HTTP Server section of the Server document. For more information, see Administering
the Domino System.

Adding graphics to a page, form, or subform


There are four ways to add a graphic to a page, form, or subform:
v Copy and paste
v Import a graphics file
v Create a picture
v Insert an image resource

To copy and paste a graphic


1. Copy a graphic to the clipboard.
2. Open the page or form and move the cursor to where you want to place the graphic.
3. Choose Edit - Paste.

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


You can import different types of graphics files into a page, form, or subform.
1. Move the cursor where you want to place the graphic.
2. Choose File - Import.
3. Select the graphic file to import and click Import.

To create a picture
1. Move the cursor to where you want to place the picture.
2. Choose Create - Picture.
3. Select a graphic to import and click Import.

To insert an image resource


1. Move the cursor where you want to place the graphic.
2. Choose Create - Resource - Insert Resource.
3. Under Databases, select the database from which you want to insert the image resource.
4. Under ″Resource type,″ select Images.
5. Under ″Additional resources,″ select an image to insert from the list of images.
6. Click OK to display the image in the form, document, or page.

Chapter 4. Designing pages 59


Changing the display properties of the graphic
Once you have added a graphic, you can change its display properties using the properties box. Keep in
mind that Domino passes the size and scaling information for graphics to the browser. If the browser
supports scaling, the graphic has the same size and scale as it does in Notes; otherwise, the graphic
appears in its original size, regardless of how you size it.

To resize a graphic
1. Select the graphic.
2. Choose Picture - Picture Properties.
3. Do one of the following:
v Drag the box in the graphic’s lower right corner to resize the graphic.
v In the Scaling field of the properties box, enter a value for the width and height.

To return a graphic to its original size


1. Select the graphic.
2. Choose Picture - Picture Properties.
3. On the Picture Info tab, click ″Reset.″

To set the text wrap properties for the graphic


There are several alignment and text wrap properties you can set in the Picture Properties box.
1. Select the graphic.
2. Choose Picture - Properties.
3. At the Picture Info tab, choose one of the options for wrapping text around the graphic from the ″Text
Wrap″ drop-down list.
By default, Designer aligns a picture with the bottom of the text around it. To wrap text around the
picture, choose either ″Wrap, float image left″ (so that text appears to the right of the image) or
″Wrap, float image right″ (so that text appears to the left of the image).

To add alternate text for the Web


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

To add a caption
1. Select the graphic.
2. Choose Picture - Picture Properties.
3. At the Picture Info tab, enter text in the Caption box. Click the check mark to accept the text.
4. Select a display option for the caption.

Adding a background color or graphic


You can paste or import a BMP, JPEG, GIF, PCX Image, or TIFF 5.0 bitmap graphic file as a background
for a page, form, or subform. If the graphic is the same size as the page, form, or subform, it appears
once; smaller graphics ″tile″ to fill the background. All page or form elements appear in front of
background.

60 Application Development with Domino Designer 7


In addition, you can add a background color to enhance a page or form. You might want to use a
standard color for a particular type of page or form, for example, white for a request page.

To have the background show through part of an image, create a transparent GIF file with an image
editor or utility and then import the image. Both Notes and Web users see transparent background
images.

To choose a background color


1. Open the page, form, or subform.
2. Choose Design - <Design element > Properties and click the Background tab.
3. Select a background color.

To paste a bitmap as a background


1. Copy to the clipboard the bitmap you want to use as a background.
2. Open the page, form, or subform.
3. Choose Design - <Design element> Properties and click the Background tab.
4. Click ″Paste Graphic″ to display the graphic as the background.

To import a BMP, JPEG, GIF, PCX Image, or TIFF 5.0 bitmap as a background
1. Choose Design -<Design element> Properties and click the Background tab.
2. Click ″Import Graphic″ and select the file to import.
3. Click OK.

To delete the background


1. Choose Design - <Design element> Properties.
2. Click the Background tab and then click ″Remove Graphic.″
For more information on pictures and on graphics, see the Notes Client Help.

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

The Designer elements that you can display as applets include outlines, views, rich-text fields, and action
bars. For more information, see the topics for creating an outline applet, view applet, editor applet, and
action bar applet.

For custom or prebuilt applets you want to include in a page or form, follow the steps for inserting,
modifying, and running applets described in the chapter ″Including Java Applets in an Application.″

Creating an attachment
Add a file attachment to make the file available for users to launch or detach. You can also create
attachments to store files. For example, attach a file for use in a Web application, so that it can be
accessed using a Domino URL.

For more information about opening an attachment with a URL command, see the appendix ″URL
commands for Web Applications.″
1. Open the page, form, or subform.
2. Move the cursor to where you want to create the attachment.

Chapter 4. Designing pages 61


3. Choose File - Attach.
4. Select the file and click Create.

Embedding elements
Embedded elements are objects and controls that can be embedded on a page, form, subform, or
document. Elements that can be embedded include:
v Views
v Folders
v Outlines
v Navigators
v Date pickers
v Instant Messaging Contact List

Embedding elements makes it easier to design a single application for use by both Notes clients and Web
browsers. Many Notes elements display differently when viewed on a browser. Embedded elements
provide functionality in Web applications that closely resemble functionality already available in Notes
applications. Additionally, embedding lets you combine elements on a page or form and use a full range
of design features, including frames, tables, styled text, borders, and graphics, to create a high-impact
design.

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

To delete an embedded element


1. Select the embedded element.
2. Choose Edit - Delete.

Embedding a date picker


The embedded date picker is a navigational tool that works with open calendar views. You can use an
embedded date picker on a page or form to customize a calendar application. The embedded date picker
displays a monthly calendar and the user can choose a month and a day of the month.

If you use a date picker in a frameset with a calendar view, clicking a specific day in the date picker
broadcasts a message to the frameset to display the corresponding day in the calendar view and also
displays all calendar entries for that day. Note that the embedded date picker must be in the same
frameset as the calendar view and the calendar view must be open. This feature is not supported on the
Web.

To use a graphical calendar pop-up to make filling in a date/time field easier for users, see the topic
″Creating a graphical display for Date/Time″ in the chapter ″Designing Fields.″

Beginning with Lotus Domino Designer 6, you can specify the calendar view with which to use the
embedded date picker. This is important if there is more than one calendar view in a frameset. To specify
the calendar view, go to the Info tab of the Date Picker Properties box. Enter a target frame so that the

62 Application Development with Domino Designer 7


date selected appears only in the calendar in the target frame. If you do not specify a target frame, all
calendar views in the frameset switch to the day selected in the date picker.

To embed a date picker


1. Move the cursor where you want the date picker to display on a page, form, subform, or the rich-text
field of a document.
2. Choose Create - Embedded element - Date picker.
3. Select the date picker and choose Element - Date Picker Properties to set the following properties:
v Horizontal and vertical size
v Font style and color
v Alignment and spacing
v Hide-when options
v Target frame

Embedding an Instant Messaging Contact List


If you are designing a Notes application that is integrated with Lotus Instant Messaging, you can embed
a contact list so that users will see their contact list displayed on a page or document.
1. Move the cursor where you want the Contact List to display on a page, form, subform, or the
rich-text field of a document.
2. Choose Create - Embedded element - Instant Messaging Contact List.
Your contact list displays. A user opening the page or document will see their own contact list.

Note: This feature is not available for Web applications.

Inserting a JavaScript library


A JavaScript library is a place for storing and sharing common JavaScript programs and code. You can
insert an existing JavaScript library into a page, form, or subform either in-line or into the JS Header.

For more information on Script libraries, see the Domino Designer Programming Guide.

To insert a JavaScript library in-line


1. Open a page, form, or subform in Designer.
2. Choose Create - Resource - Insert Resource.
3. Highlight ″JavaScript Libraries,″ select an available JavaScript library, and click OK.

To Insert a JavaScript Library into the JS Header:


1. Open a page, form, or subform in Designer.
2. Select the JS Header event in the info list under the Objects tab
3. Choose Create - Resource - Insert Resource.
4. Select an available JavaScript library, and click OK.

Using HTML on a page, form, or subform


There are a number of ways you can include HTML on a page, form, or subform when you are
designing. If you have existing HTML or you prefer to use HTML instead of the formatting tools
Designer offers, you have the following options:
v Convert a page, form, or subform (or sections of the page, form, or subform) to HTML and use the
HTML editor to change the HTML.

Chapter 4. Designing pages 63


v Import HTML, thus using the source of an existing Web page or form as the base of a new page or
form. Designer renders the imported HTML on the page, form, or subform already translated from
HTML.
v Paste HTML directly on a page, form, or subform. The HTML stays in HTML format.
v Enter HTML directly on a page, form, or subform. The HTML stays in HTML format.

To convert pages, forms, or subforms into HTML


You can convert some or all of the contents of a page, form, or subform into HTML source code and then
use the HTML editor to make changes to the HTML source code.
1. Open a page, form, or subform in Designer.
2. Select the contents of the page, form, or subform that you want to convert to HTML.
3. Choose Edit - Convert to HTML. The selected contents are converted into HTML source code.
Because not everything in Notes has an exact equivalent in HTML, the conversion to HTML is an
approximation. You should always check your conversion results.
If you mistakenly convert something to HTML, choose Edit - Undo Delete to recover. Do not choose
Edit - Convert to Notes because the conversion is not exact.

Note: Buttons in Web applications that have JavaScript associated with the Click event are converted
to HTML as expected. However, buttons that do not have JavaScript associated with the Click event
are not converted to HTML. For the buttons not converted to HTML, choose Edit - Undo Delete so
that the deleted button reappears on the page, form, or subform.
4. To use the HTML editor, place the cursor anywhere in the newly created HTML source code and
choose View - HTML pane.
The screen splits. The page, form, or subform appears in the top pane (in an embedded Internet
Explorer browser control) and its HTML source code appears in the bottom pane.
5. You can edit the HTML source code in the bottom pane. Click Refresh to see the results in the top
pane of your HTML changes.
6. Press ESC to exit from the HTML editor.
7. (Optional) To convert the HTML to a Notes format, place the cursor anywhere in the HTML source
code in the top pane and choose Edit - Convert to Notes Format.
Note that the conversion to Notes format is an approximation. You should check your conversion
results. If you convert to HTML and then back to Notes, you may get unexpected results.

To import HTML
To import HTML you must first save it as a file that you can access.
1. Open a page, form, or subform.
2. Choose File - Import.
3. Select the file containing the HTML you want to import and click OK. Designer translates the HTML
and then adds it to the page, form, or subform.

To paste HTML
1. Select the content you want to paste from the source of an existing Web page, form, or subform.
2. Copy the content to the clipboard.
3. Open a page, form, or subform.
4. Choose Edit - Paste.
5. Open the Properties box for the page, form, or subform (Design - <design element> Properties).
6. At the Info tab, check ″Render pass through HTML in Notes.″

64 Application Development with Domino Designer 7


To enter HTML directly on a page, form, or subform
1. Open a page, form, or subform.
2. Enter the HTML directly on the page, form, or subform.
3. Open the Properties box for the page, form, or subform (Design - <design element> Properties).
4. At the Info tab, check ″Render pass through HTML in Notes.″

When you check ″Render pass through HTML in Notes,″ Domino passes all data on the page, form, or
subform directly to the browser. Domino ignores embedded navigators and folders and any embedded
views that don’t have ″Render pass through HTML in Notes″ selected.

To include some HTML on a page, form, or subform


If you do not want the entire page, form, or subform treated as HTML, you can include some HTML on
the page, form, or subform and mark this text as HTML. Designer serves it correctly to the browser.
1. Enter or paste HTML on the page, form, or subform.
2. Select the text and choose Text - Pass-Thru HTML.

Note: Pages, forms, or subforms containing pass-thru HTML may display differently in the Notes client
than on a browser. For example, if you create nested tables by using pass-thru HTML, the table may
contain more white space when displayed in the Notes client than when displayed in a browser.

Setting launch properties for pages or forms


You can set auto launch properties for pages and for forms at the Launch tab of the appropriate
properties box.

To set the launch property for a page


1. Open the page.
2. Choose Design - Page Properties. The Page Properties box opens.
3. Click the Launch tab.
4. Select one of the following objects to launch automatically when a user opens the page:
v First Attachment
v First Document Link
v First OLE Object
v None (default)
v URL
5. Set the frameset that the page will be associated with and the frame within that frameset.

To set the launch property for a form


1. Open the form.
2. Choose Design - Form Properties to open the Form Properties box.
3. Click the Launch tab.
4. For forms, select one of the following objects to launch automatically when a user opens the
document created with this form:
v First Attachment
v First Document Link
v First OLE Object
v None (default)
v URL

Chapter 4. Designing pages 65


v Other objects, including the following:
Bitmap Image, Lotus ScreenCam Movie, Lotus Word Pro 9 Document, Media Clip, MIDI Sequence,
Netscape Hypertext Document, Package, Paintbrush Picture, Wave Sound, WordPad Document.
5. (URL only) If you choose URL, follow these steps:
v Create a rich text field on the form and name the field URL.
v At the Launch tab of the Form Properties box, select URL.
v Create a document using this form.
v In the rich text field named URL, create a Link Hotspot (Create - Hotspot - Link Hotspot) for the
URL you want to automatically launch.
v Close and reopen the document and the Web page should display in your browser.
6. If applicable, set the frameset that the form will be associated with and the frame within that
frameset.

Layers
Layers let you position overlapping blocks of content on a page, form, or subform. Layers give you
design flexibility because you can control the placement, size, and content of information. You can create
and stack multiple layers beneath and above one another. Transparent layers reveal layers underneath;
opaque layers conceal layers underneath.

The content of a layer depends on whether you create a layer on a page or a form. When you create a
layer on a page, a layer can contain the same elements that a page can contain; for example, you can add
text and graphics, and so on. When you create a layer on a form, a layer can contain the same elements
that a form can contain; for example, you can add text and graphics, as well as controlled-access sections,
fields, and subforms.

After you create a layer, you can change the following properties of the layer:
v Position
v HTML properties
v Background color and image

Creating a layer
If the layer you need is similar to one that exists in the same database, another database, or a Designer
template, you can copy and paste the layer and then modify it. If no existing layer suits your purpose,
create a new layer.

To create a new layer


Follow these steps to create a new layer on a page. Note that you follow a similar process to create a
layer on a form or subform.
1. Click Pages in the Design pane.
2. Click ″New Page.″
3. Choose Create - Layer.
4. Create the contents for the layer, such as text and graphics.
5. Choose Layer - Layer Properties to assign the following layer properties:
v On the Position tab, change the position of the layer.
v On the Background tab, select the background color or graphic for the layer.
v On the HTML tab, specify the HTML for the layer.

66 Application Development with Domino Designer 7


To copy an existing layer
1. Select the layer that you want to copy.
2. Choose Edit - Copy to copy the layer to the clipboard.
3. Choose the location for the new layer.
4. Choose Edit - Paste to paste the copy into the new location.

To delete a layer
1. Select the layer that you want to delete.
2. Press Delete or choose Edit - Cut.

Layer anchors
Each layer has its own anchor. If you move the layer, the anchor remains in place. To display or change
the name of the layer, right-click the layer anchor. The Layer Anchor Properties box appears with the
current name of the layer.

To hide a layer
You can hide a layer by changing the ″Hide When″ properties of the paragraph containing the layer
anchor. Move the cursor to the paragraph containing the layer anchor, choose Text - Text Properties, and
click the Hide When tab.

If a layer anchor is contained in a collapsed section or in a non-current row of a tabbed table, the layer
and its contents are not visible until the collapsed section is expanded or until the row is current.

To hide a layer for the current session only


You can hide a layer for the current Designer session by using the Layer Tree dialog box.
1. Open a page, form, or subform and create one or more layers.
2. Choose Design - Layer Tree. The Layer Tree dialog box appears listing all the layers (and their
hierarchies) on the page, form, or subform.
3. Select a layer. Click the Hide/Show button to hide or show the layer while you edit the form or page
in Designer.
4. To hide all layers for the current session, click ″Hide All.″ To show all layers for the current session
click ″Show All.″
5. Click Close.

Changing the position of a layer


When you create a layer, it contains default position values. You can change the position of a layer in
several dimensions by changing its position values. Note that you specify a layer position in relation to
the block that contains it (also called the parent element).
1. Select the layer.
2. Choose Layer - Layer Properties and click the Positioning tab.
3. Choose a position and position value, as described in the following table:

Layer
Position Description Default value
Top Specifies the location of the top edge of the layer. ″Auto″ aligns the top of the layer vertically
with its original location (insertion point).
Left Specifies the location of the left edge of the layer. ″Auto″ aligns the left edge horizontally with
its original location (insertion point).
Width Specifies the width of the layer, a value based on the One-third of the width of the window or the
location of its right edge relative to its left edge. parent element, whichever applies.

Chapter 4. Designing pages 67


Layer
Position Description Default value
Height Specifies the height of the layer, a value based on the One-third of the height of the window or the
location of its bottom edge relative to the top edge. parent element, whichever applies.
Z-Index Specifies the stacking order of the layer; that is, how 0; that is, in front of the parent element.
close to or far from the front of the parent element
the layer is located.

Table of values for layer positions


The following table summarizes the possible values for each position.

Layer Position Value Description


Top Pixels The location in pixels from the top edge of the parent element.
Inches The location in inches from the top edge of the parent element.
Ems The location in em units from the top edge of the parent element.
Percent The location from the top edge of the parent element, computed as a percentage
of the height of the parent element.
Characters The location in characters from the top edge of the parent element.
Auto The default location of the top edge. The layer top edge is aligned vertically
with the top edge of the original insertion point.
Left Pixels The location in pixels from the left edge of the parent element.
Inches The location in inches from the left edge of the parent element.
Ems The location in em units from the left edge of the parent element.
Percent The location from the left edge of the parent element, computed as a percentage
of the width of the parent element.
Characters The location in characters from the left edge of the parent element.
Auto The default location of the left edge. The layer left edge is aligned horizontally
with the left edge of the original insertion point.
Width Pixels The layer’s width in pixels.
Inches The layer’s width in inches.
Ems The layer’s width in em units.
Percent The layer’s width, computed as a percentage of the width of the parent element
Characters The layer’s width in characters.
Auto ″Auto″ sets the width automatically based on the layer’s contents.
Height Pixels The layer’s height in pixels.
inches The layer’s height in inches.
Ems The layer’s height in em units.
Percent The layer’s height, computed as a percentage of the height of the parent
element.
Characters The layer’s height in characters.
Auto ″Auto″ sets the height automatically based on the layer’s contents.

68 Application Development with Domino Designer 7


Layer Position Value Description
Z-Index Integer A layer with a higher Z-Index value (for example, layer A) is located closer to
the user; that is, it is stacked in front of a layer with a lower Z-Index value (for
example, layer B). If the layers overlap and layer A is opaque, the contents of
layer A obscure the contents of layer B. In addition, the contents of layer B
cannot be clicked or selected, even if layer A is tranparent.

A negative Z-Index is placed behind the parent element’s contents (so that it
cannot be clicked or selected); a positive Z-Index (>=0) is placed in front of the
parent element’s contents (and prevents overlapped parent element content from
being clicked or selected).

Changing the HTML properties of a layer


If you are designing an application for the Web and are using HTML 4.0, the HTML tab lets you apply
core attributes that are common to layers. Domino incorporates the values of these attributes to the
HTML that it creates at run time. When you are using the HTML tag attributes, remember that the HTML
must be ASCII characters. Also, do not include quotation marks when you enter the attributes in the
various boxes, except in the Other box, as described in the table that follows.
1. Select a layer.
2. Choose Layer - Layer Properties and click the HTML tab.
3. Specify HTML attributes, as described in the table that follows:

Tag Description
ID The ID attribute; in this case, Layer.
Class Use the Class attribute to apply a CSS class for a defined object. For example, if the object’s
name is ZipCode, the class could be Numeric. CSS styles are defined in the HTML Head
Content event for a form or page.
Style Use the Style attribute to apply a specific CSS style to an object using inline CSS. For example, if
the object’s name is ZipCode, the class is Numeric, the style could be font-size:10pt. If you have
more then one value, separate them with a semicolon; for example, font-size:10pt; color:blue.
Title Generally use the Title attribute in Explorer 4.x and later to provide the user with a tip or
prompt. For example, if the object’s name is ZipCode, the class is Numeric, the title could be:

Enter your Zip Code.

Note that the title displays differently on different browsers.


Other Use the Other attribute for additional HTML tag attributes, which must be written as pure
HTML code. For example, instead of writing ZipCode in the Name/ID box, you write
ID=″ZipCode.″

Changing the background color and image for a layer


You can use color and images in stacked layers to great effect. If you have created several layers and
want to obscure layers stacked underneath, use colors and images on layers with a higher Z-Index value;
if you want layers stacked underneath to show through, do not use background colors and images on
layers with a higher Z-Index value.

To choose a background color


1. Select a layer.
2. Choose Layer - Layer Properties and click the Background tab.
3. Select a background color.

Chapter 4. Designing pages 69


To insert an image resource as the background
1. Select a layer.
2. Choose Layer - Layer Properties and click the Background tab.
3. Click the folder icon. The Insert Image Resource dialog box appears.
4. Select an image resource and click OK. The image becomes the background for the layer.

To create an image using a formula


1. Select a layer.
2. Choose Layer - Layer Properties and click the Background tab.
3. Click the @ icon to enter a formula that resolves to an image.

To change the tile pattern of an image


1. Select a layer.
2. Choose Layer - Layer Properties and click the Background tab.
3. Choose one of the following tile patterns.

If you choose this pattern The image


Tile Repeats in rows and columns to fill the entire layer
Repeat once Appears in the upper left corner of the layer
Repeat vertically Appears in multiple copies along the left edge of the layer
Repeat horizontally Appears in multiple copies along the top edge of the layer
Center Appears in the center of the layer
Size to fit Expands to fill the entire layer

Creating style sheets as shared resources


Cascading style sheets (CSS) give you the ability to control many aspects of your page layout, including
headers, links, text, fonts, styles, color, and margins. You can browse your local file system for a CSS, turn
it into a shared resource, and then insert it into a page, form, or subform.

To create a new style sheet resource


1. Expand ″Shared Resources″ in the Design pane.
2. Select ″Style Sheets″ from the list of resources.
3. Click ″New Style Sheet Resource.″ The Browse dialog box opens. Only files with a CSS extension
appear.
4. Find and select the cascading style sheet you want to use.
5. Click Open to add the style sheet to the list of style sheet resources. The Style Sheet Resource
Properties box opens, so you can change the name or other properties of the style sheet.

To insert a style sheet resource into a page, form, or subform


1. Open a page, form, or subform.
2. Place the cursor where you want to add the style sheet. To insert the style sheet in the HTML Header,
open the Programmer’s pane, select the HTML Head Content event, and click in the script area.
3. Choose Create - Insert Resource. The Insert Resource dialog box appears.
4. Select the database containing the style sheet. The default is the current database.
5. Select ″Style Sheets″ as the resource type.
6. In the Available resources section, highlight the style sheet resource to add.
7. Click OK.
70 Application Development with Domino Designer 7
8. (Optional) To view the name of the inserted style sheet resource or to change to another style sheet
resource, choose Style Sheet - Style Sheet Properties. The Style Sheet Properties box appears with the
name of the style sheet resource. To select a different style sheet resource, click the Locate Object
folder.

To edit a style sheet resource


1. Expand ″Shared Resources″ in the Design pane.
2. Select ″Style Sheets″ from the list of resources.
3. Select a style sheet resource.
4. Do one of the following:
v If you have a default style sheet editor, click ″Open File″ to edit the resource.
v Click ″Open With″ and select an editor to open the style sheet resource.

To refresh a style sheet resource


To update a file you have copied as a shared resource, you can refresh the style sheet resource.
1. Expand ″Shared Resources″ in the Design pane.
2. Select ″Style Sheets″ from the list of resources.
3. Select a style sheet resource.
4. Click Refresh. The Open dialog box appears.
5. Select the CSS file to refresh your style sheet resource and click Open. The style sheet resource is
updated.

Table of supported CSS properties


The following table shows the Cascading Style Sheet properties that Domino Designer supports. The
HTML tags automatically map to Notes. For example, this tag automatically maps to Notes:
BODY {Font-Family: Arial; Color: Blue}

Use this key to read the table:

Yes = property is supported

N/A = not applicable

N/S = not supported

Note the following:


v A property set via the style sheet resource takes precedence over a conflicting property set in the
element’s properties box.
v Border-top-color and border-color are applied to all four sides of the element.
v Border-top-style and border-style are applied to all four sides of the element.
v For image, the following properties are applied to the image caption: color, font-weight, font-style,
font-size, font-family, and text-decoration.
v The visibility property is not listed in the table because of its minimal support. It is supported only for
the <DIV> tag for hidden and collapse values.

Document Layer Paragraph List Item Table Cell Graphic

List of Properties <Body> <DIV> <P> <LI> <TABLE> <TD> <IMG>


background-color Yes Yes N/S N/S Yes Yes N/A
background-image N/S N/S N/A N/A

Chapter 4. Designing pages 71


Document Layer Paragraph List Item Table Cell Graphic

List of Properties <Body> <DIV> <P> <LI> <TABLE> <TD> <IMG>


background-repeat N/S N/S N/A N/A
border-bottom-width N/A N/A Yes Yes Yes Yes Yes
border-color N/A N/A Yes Yes Yes Yes Yes
shorthand
border-left-width N/A N/A Yes Yes Yes Yes Yes
border-right-width N/A N/A Yes Yes Yes Yes Yes
border shorthand N/A N/A Yes Yes Yes Yes Yes
border-style N/A N/A Yes Yes Yes Yes Yes
shorthand
border-top-width N/A N/A Yes Yes Yes Yes Yes
border-top-color N/A N/A Yes Yes Yes Yes Yes
border-top-style N/A N/A Yes Yes Yes Yes Yes
border-width N/A N/A Yes Yes Yes Yes Yes
shorthand
color Yes Yes Yes Yes Yes Yes Yes
font-family Yes Yes Yes Yes Yes Yes Yes
font-size Yes Yes Yes Yes Yes Yes Yes
font-style Yes Yes Yes Yes Yes Yes Yes
font-weight Yes Yes Yes Yes Yes Yes Yes
height N/A Yes N/A N/A N/A N/A N/A
left N/A Yes N/A N/A N/A N/A N/A
margin-bottom N/A N/A Yes Yes Yes N/A Yes
margin-left N/A N/A Yes Yes Yes N/A Yes
margin-right N/A N/A Yes Yes Yes N/A Yes
margin shorthand N/A N/A Yes Yes Yes N/A Yes
margin-top N/A N/A Yes Yes Yes N/A Yes
padding-bottom N/A N/A Yes Yes Yes N/A Yes
padding-left N/A N/A Yes Yes Yes N/A Yes
padding-right N/A N/A Yes Yes Yes N/A Yes
padding shorthand N/A N/A Yes Yes Yes N/A Yes
padding-top N/A N/A Yes Yes Yes N/A Yes
position N/A Yes N/A N/A N/A N/A N/A
text-decoration Yes Yes Yes Yes Yes Yes Yes
top N/A Yes N/A N/A N/A N/A N/A
width N/A Yes N/A N/A N/A N/A N/A
z-index N/A Yes N/A N/A N/A N/A N/A

72 Application Development with Domino Designer 7


Programming a page or form
A page or form has events associated with it that you can use to run a simple action, a formula, a
LotusScript routine, or a JavaScript program. To see what events are available for a page or form, open
the page or form in Designer and look at the list of events in the Objects tab in the Programmer’s pane.
When you select an event, the programming choice for that event appears to the right of the Object tab.
For example, if you select the onLoad event for the Web, you program it using JavaScript or Common
JavaScript. If you select the onLoad event for the client, you can use JavaScript, Common JavaScript,
LotusScript, or Formula.

For information on each event and an example of how to program them, see the Domino Designer
Programming Guide.

Adding HTML header information


The HTML Head Content event on a page or form lets you pass HTML information, such as a Meta tag,
to the <Head> tag for a document.

To add HTML header information


1. In the Programmer’s pane, click the Objects tab.
2. Select the ″HTML Head Content″ event.
3. Enter the HTML in the Script area of the Programmer’s pane.
4. Click the green check mark to validate your work.

Example: Adding HTML to the Head tag


This example uses the HTML Head Content event to add the Meta tag ″keyword″ with a value of ″gold″
to the <Head> tag in a document.
"<meta name=\"keyword\" content=\"gold\">"

Adding JavaScript header information


Use the JS Header event to store any JavaScript functions that you want to call from other events on the
page or form. You do not have to include the <SCRIPT> tags. Domino creates those for you and puts the
script into the <HEAD> tag of the HTML page or form.

To add JavaScript header information


1. In the Programmer’s pane, click the Objects tab.
2. Select the ″JS Header″ event.
3. Enter script in the Script area.
4. Click the green check mark to validate your work.

Example: Adding JavaScript header information


This example uses JavaScript and cookies to load a page or form into the browser and save a cookie
called ″Cookie_Man″ in the user’s cookie file. It also displays a message that shows the number of times
a user has visited the site. It uses two functions, doCookie() and getTimes(), written in the JS Header.
These functions are called from the onLoad event.

Note: The actual expiration date in the code has to be changed to a future date in order to make the
cookies work properly.

In the JS Header Event enter the following code:


cookieName = "Cookie_Man";

Chapter 4. Designing pages 73


function doCookie() {
var index = -1;
if(document.cookie) {
index = document.cookie.indexOf(cookieName);
}
if (index == -1) {
document.cookie = cookieName +
"=1; expires=Saturday, 03-Apr-2010 08:00:00 GMT";
} else {
var countbegin = (document.cookie.indexOf("=", index) + 1);
var countend = document.cookie.indexOf(";", index);
if (countend == -1) {
countend = document.cookie.length
}
var count = eval(document.cookie.substring(countbegin, countend)) + 1;
document.cookie=cookieName+"="+count+"; expires=Saturday, 03-Apr-2010 08:00:00 GMT";
}
}
function getTimes() {
if(document.cookie) {
var index = document.cookie.indexOf(cookieName);
if (index != -1) {
var countbegin = document.cookie.indexOf("=", index)+ 1);
var countend = document.cookie.indexOf(";", index);
if (countend == -1) {
countend = document.cookie.length;
}
return document.cookie.substring(countbegin, countend);
}
}
return 0;
}

The onLoad page or form event contains the following code:


doCookie(); // Grab the cookie information
document.forms[0].visited.value = getTimes(); // format visited count into the document

Create a text field on the form named ″Visited.″

Include the text on the form:

You have visited this site <Visited> time(s) before.

74 Application Development with Domino Designer 7


Chapter 5. Designing forms
Forms, like pages, display information. Everything that can be done with a page can be done with a
form. What sets forms apart from pages is that forms can be used to collect information. A form provides
the structure for creating and displaying documents, and documents are the design elements that store
data in the database. When a user fills out the information in a form and saves it, the information is
saved as a document. When a user opens the document, the document uses the form as a template to
provide the structure for displaying the data.

Here are the basic steps involved in designing a form:


1. Decide on the purpose and type of form you need. To do so, consider:
v The kind of information you want to collect and which elements you need.
v How and where the resulting documents, which contain and display the collected information,
appear.
2. Create the form.
3. Add elements to the form.
4. Name the form.
5. Assign its properties.
6. Preview and test the form in the browsers users access it with.

Form elements
You can use the following elements in a form or subform. Many of these elements can also be used in
pages.

Element to use on a form


or subform Description
Actions Actions automate tasks for the user. Add actions to the menu in the Notes client, or add
actions with buttons or hotspots on a form, subform, or page. For more information, see
the topic Actions in the chapter ″Adding Automation to Applications.″
Applets Use Java applets to include small programs, such as an animated logo or a
self-contained application, in a form, subform, or page. For more information on
including Java applets, see the chapter ″Including Java Applets in Applications.″
Attachments You can attach files to a form, subform, or page so users can detach or launch files
locally.
Automation You can create form actions, buttons, or hotspots on a form, subform, or page to
automate simple or complex tasks. For more information on creating these elements see
the chapter ″Adding Automation to Applications.″
Computed text Use computed text to generate dynamic text based on formula results.

75
Element to use on a form
or subform Description
Embedded elements You can embed the following elements in a form, subform, or page:
v Embedded outline
v Embedded view or folder pane
v Embedded navigator
v Embedded date picker

You can embed the following elements only in a form or subform:


v Embedded file upload
v Embedded scheduler
v Embedded editor

You can use any of these embedded elements alone or combine them to control how
users navigate through your application.
Fields Fields are the design elements that collect data. You can create fields only on forms or
subforms. Each field on a form stores a single type of information. A field’s field type
defines the kind of information a field accepts. You can place fields anywhere on a
form. For information on fields, see the chapter ″Designing Fields.″
Graphics You can place a graphic anywhere on a form, subform, or page. The graphic appears on
the page or on any document created with the form or subform. For example, on a form
for correspondence, placing your company logo at the top of the form creates a
letterhead. For more information on using graphics on a page, form, or subform, see the
topic ″Using graphics″ in the chapter ″Designing Pages.″
Horizontal rules You can add horizontal rules to separate different parts of a form, subform, or page.
HTML You can use HTML on forms, subforms, and pages. You can either write your own
HTML or use existing HTML by importing or pasting the HTML. You can also convert a
form or page to HTML and use the HTML editor.
Imagemaps Imagemaps are graphics you enhance with programmable hotspots that perform some
action when clicked by a user. Imagemaps are often used as navigational structures in
an application. You can use them on a form, subform, or page.
JavaScript libraries You can find and insert JavaScript libraries into a page, form or subform. For more
information on inserting JavaScript libraries, see the topic ″Inserting a JavaScript library″
in the chapter ″Designing Pages.″
Layers Layers let you position overlapping blocks of content on a form, subform, or page.
Layers give you greater design flexibility because you can control the placement, size,
and content of the information. For more information on layers, see the topic ″Layers″
in the chapter ″Designing Pages.″
Layout region A layout region is a fixed-length design area in which related elements can be moved
easily and be displayed in ways not possible on regular forms and subforms. A layout
region can contain static text, graphics, buttons, and all fields except rich text fields. You
can hide or collapse a layout region and all its components under certain conditions.
Layout regions are not supported for Web applications. For more information on layout
regions, see the topic ″Layout regions″ in this chapter.
Links Within a form, subform, or page, you can add links to databases, views, specific
documents, or URL links that open pages on the Internet.
Sections A section is a collapsible and expandable area defined on a form or subform. It can
include fields, objects, layout regions, and text. For more information on sections, see
the topic ″Creating sections″ in the chapter ″Designing Pages.″

An access-controlled section allows only certain users to edit the fields in the section.
For information on creating an access-control list for a section, see the topic ″Creating
access-controlled sections″ in the chapter ″Security in an application.″

76 Application Development with Domino Designer 7


Element to use on a form
or subform Description
Shared resource The following shared resources can be added to a form or subform:
v Images
v JavaScript libraries
v Shared fields
v Subforms
v Style sheets
v HTML Files
Style sheet (CSS) shared You can find and insert a cascading style sheet (CSS) as a shared resource on a page,
resources form, or subform. For more information on style sheets, see the topic ″Creating style
sheets as shared resources″ in the ″Designing Pages″ chapter.
Subforms A subform is a collection of form elements stored as a single object. A subform can be a
permanent part of a form or can appear conditionally, depending on the result of a
formula. Subforms save redesign time. When you change a field on a subform, every
form that uses the subform changes. Common uses of subforms include adding a
company logo to business documents or adding mailing label information to mail and
memo forms. For more information on including subforms, see the topic Subforms in
this chapter.
Tables Use tables in forms, subforms, and pages to summarize information or to align elements
such as fields and graphics in rows and columns. For information on creating
programmable tables, see the topic ″Creating programmable tables″ in the chapter
″Designing Pages.″
Text Text is often used to label fields so users understand the purpose of each field. For more
information on formatting text, see Lotus Notes Help.

For information on creating and formatting tables, see the topic ″Creating tables″ in Lotus Notes Help.
You can also press F1 while you are creating a table to get online help.

Forms and documents


When a user creates and fills out the information in a form and saves it, the information is saved as a
document. When a user opens the document, the document uses the form as a template to provide the
structure for displaying the data. When designing forms, you should consider where and how the
resulting documents will be displayed.

A form is stored in the database it was created in and used to display all associated documents. However,
there may be times when you are mailing a document to a database that does not have the form that was
used to create the document. In those cases you can designate the form to be stored with each document
created from it. Storing the form with each document does consume more memory.

When a user opens a document, Domino uses these rules to determine which form to use to display it:

Condition Form used to display document


If the form used to create the document is The form that was used to create the document. The original form
available and there is no form stored in the name is stored in a hidden field called ″Form″ in the document.
document and no form formula To find the value of the field you can check the Document
Properties box under the Fields tab.
If a form is stored with the document The form stored with the document. (When a form is stored in a
document, the form name is stored in an internal field called
$Title.)
If the view has a form formula The form is determined by the view’s form formula.

Chapter 5. Designing forms 77


Condition Form used to display document
If the form used to create the document is not The default form for the database. Each database can have only
available in the database one default form, which is marked with an arrow in the Forms
list.

Storing a form with each document


Storing the form with each document allows the document to display correctly even in a database where
the form is missing, renamed, or deleted. This feature uses more system memory and may require as
much as 20 times more disk space. Note that if you change the form design, there is no easy way to
update all of the stored copies of the form. In general, store a form in a document only under these
conditions:
v The database to which documents are mailed or pasted does not contain a copy of the original form.
v The database to which documents are mailed or pasted doesn’t share an alias with the original form.
v The form contains an embedded OLE object or a subscription, and you want documents to reflect any
changes to the object.
v You selected ″Include in Search Builder″ in the Form Properties box and want the form’s static text to
be searchable.

Note: Be aware that forwarding a document does not forward a form or its field definitions. If there are
instances where you need to forward the form and its definitions, you can check ″Store form in
document″ on the Form Info tab of the Form Properties box.

To store a form with each document


1. Open the form.
2. Choose Design - Form Properties.
3. Click the Form Info tab.
4. Select ″Store form in document″ and close the Form Properties box.
5. Open the Database Properties box. At the Database Basics tab, check ″Allow use of stored forms in
this database″ and close the Database Properties box.

Overriding the stored form


When a form is stored in a document, the form name is stored in a hidden field called $Title. Additional
information is stored in the $Info, $WindowTitle, and $Body fields. To use a different form to display the
document, create an agent that deletes this stored form information and designates another form to
display the document.

Shared fields and documents with stored forms


If the form contains a shared field, that field is converted to a single–use field in the copy of the form
that is stored in the document. This ensures that if a copy of the document is stored in a database that
does not contain the shared field definition, the field can still be used. In the original form, the field is
still defined as shared.

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

For more information on writing form formulas, see the Domino Designer Programming Guide.

78 Application Development with Domino Designer 7


Designating a default form for a database
1. Open the Form Properties box.
2. Click the Form Info tab.
3. Select ″Default database form.″

Alternatives to storing forms


As an alternative to storing the form in a document, you can use the LotusScript Send method to design
a form you can mail along with a document. This ensures that the database will have the correct form to
display the document but won’t need to store the form with each document.

For more information on using LotusScript to mail forms with documents, see theDomino Designer
Programming Guide.

Creating and deleting forms


To create a form, you must have at least Designer access in the database ACL.

If the form you need is similar to one that exists in the same database, another database, or a Designer
template, copy the form and then modify it.

To create a new form


1. In an open database, click Forms in the Design pane, and then click New Form.
2. Design the form. Create fields, text, and other elements on the form.
3. Choose Design - Form Properties to assign a name and other form properties.

To copy an existing form


1. In the Design pane, click Forms.
2. From the list of forms in the Work pane, select the form you want to copy.
3. Choose Edit - Copy to copy the form to the clipboard.
4. Open the database you want to copy the form into and click Forms in the Design pane.
5. Choose Edit - Paste to paste the copy into the list of forms in the target database.

If you are copying a form from a different database, resources such as shared fields and shared images
are not sent with the copied form. You must copy shared resources separately to the new database.

Special types of forms


There are several types of forms that you can create for specific purposes. See the following topics for
information on creating any of these types of forms.
v Profile forms
v Forms that prompt users for input
v Forms for a Domino billing application

To delete a form
Remove a form when users no longer need it. After you delete the form, documents that were created
with the deleted form are displayed with the default form instead. After you delete a form, to prevent
users from receiving a ″form can’t be found″ message, create an agent that reassigns the form name.

For information on using agents to reassign documents to a new form, see the topic ″Using agents to
update documents affected by form changes″ in the chapter ″Completing an Application and Managing
Design Changes.″

Chapter 5. Designing forms 79


1. Open the database.
2. In the Design pane, click Forms.
3. Select the form you want to delete.
4. Press DEL or choose Edit - Delete.

Tips for designing forms


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

Naming forms
Each form in a database must have a unique name. If you make a copy of a form and paste it into the
same database it came from, Designer will automatically prepend ″Copy Of″ to the form name to keep
the names unique. If you create multiple databases that contain the same information, use the same
names for the forms. Standard names enable users to recognize commonly used forms; they also make it
easier for users with similar databases to communicate. For example, suppose you have four
customer-tracking databases, one in each regional sales office. If the Southern regional manager wants to
discuss a shared account with the Western regional manager, both managers should know what a
″Company Profile″ document is.
v To name or rename a form, choose Design - Form Properties and enter a name for the form.

Name requirements
Keep the following in mind:
v The name is case-sensitive and can be any combination of characters, including letters, numbers,
spaces, and punctuation.
v If there are no synonyms or cascading name, the maximum length of the form name is 64 bytes. When
the full form name includes all synonyms and the cascading name, the maximum length is 256 bytes. If
you’re using multibyte characters, 256 bytes is different from 256 characters.
v Only the first 64 characters of a form name appear in the Create menu.

Creating aliases
A form can have additional names, called aliases. If you create an alias for a form, you can change the
form name that appears on the Create menu without having to rewrite every formula that references the

80 Application Development with Domino Designer 7


form. You can also reassign existing documents to the new form, and rewrite formulas or reassign
documents if the form name is translated. The form name and its aliases are separated by a vertical bar
(|).

If a form has only one name, it appears on the Create menu and in the document’s FORM field. If there
are two or more names, the form’s first (leftmost) name always appears on the Create menu, while the
form’s last (rightmost) name, which is typically the alias, appears in the FORM field. Sometimes a form
can have multiple names usually due to translation. In those cases the middle names are ignored. As long
as the alias does not change, documents will display using the original form and all formulas referencing
the form will continue to work.

Tip: If you add an alias to a form that is referred to in an existing view (or folder) selection formula, the
formula will not display documents created or edited after the alias is assigned. It is good design practice
to assign an alias at the same time you name a form to avoid such problems.

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

Form names and keyboard shortcuts


Windows users can select a menu item quickly by typing its keyboard shortcut (an underlined letter). If
each form begins with a different letter, the keyboard shortcut is easy to see on the Create menu.

To specify the keyboard shortcut, type an underscore (_) before the letter that you want to use. Each
keyboard shortcut must still be unique within the form list. For example, to force the letter ″v″ as the
keyboard shortcut for the Interview form, enter the name as:
Inter_view

Ordering forms on the Create menu


A form structures the data for a document that a user creates. In a Notes client application, a user
chooses a form from the Create menu to create a new document. The Create menu sorts form names in
alphabetical order. To display the forms in a different order -- for example, with the most frequently used
form appearing first -- precede the form name with a number or a letter to force the forms into the
correct sequence. If a database has too many forms to display all the forms neatly on the Create menu,
you can design a cascading menu to embed the related forms under one menu item. The Mail template
uses cascading workflow forms. When users choose Create - Special, they see these form choices:

Link Message

Phone Message

To create a cascading menu for Notes clients


1. Open the form.
2. Choose Design - Form Properties.
3. In the form name box, enter the name of the menu item you want to appear at the top level, followed
by a \ (backslash) and the form name.
To define an alias for a cascading form, insert the alias after the form name, as in: Service
Request\Hardware | HW, where HW is the alias.
4. Make sure the option ″Include in Menu: Create menu″ is checked.

Chapter 5. Designing forms 81


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

To remove a form from the Create menu in the Notes client


Removing a form from the Create menu hides the form from all users. For example, the Mail template
hides the NonDelivery Report and Return Receipt forms because only the Notes Mail Router uses them.
For compatibility with earlier releases of Notes, putting parentheses around the form names when you
name a form will also remove forms from the Create menu.
1. In the Form Properties box deselect ″Include in Menu.″
2. Save the form.

To hide a form from only some users, open the Security tab of the Form Properties box and create an
access list.

For more information on access lists, see the topic ″The database access control list″ in the chapter
″Security in an application.″

To hide a form
Another way to remove a form from the Create menu is to hide it. Hiding allows you to specify
conditions under which the form is hidden or displayed. For example, you can hide a form from Notes
clients, but display it for Web clients.
1. Close the form you want to hide.
2. In the Design pane, click Forms in the Design pane.
3. From the forms list, select the form you want to hide.
4. Choose Design - Design Properties.
5. Click the Design tab.
6. Select a hide option.

Making a form available to Web browsers


Because users do not have access to the Notes menu structure in Web applications, you must provide a
mechanism for users to create and edit documents. For example, you might design a view action for
users to create a document, and a button on the form to edit the document.

To make a form available to Web users


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

82 Application Development with Domino Designer 7


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

Selected form properties


You can use the Form Properties box to set form attributes.

To open the Form Properties box


1. Open the form.
2. Choose Design - Form Properties.

Protecting author/editor anonymity


If you want a document’s author or editors to remain anonymous, define a form that doesn’t record the
names of people who create or edit it. For complete anonymity, be sure that the author name does not
appear elsewhere on the document -- for example, in a visible computed field.

On the Form Info tab, select ″Anonymous Form.″

Changing form focus


On the Form Info tab, you can choose:
v No initial focus -- Lets you choose to have no initial focus on the form.
v No focus on F6 -- Lets you disable the F6 and SHIFT+F6 keys. These keys usually give focus to a
frame.

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

At the ″Conflict Handling″ section of the Form Info tab, choose one of the following options for the form:
v Create Conflicts -- Creates conflicts so that a replication conflict appears as a response document to the
main document. The main document is selected based on the time and date of the changes and an
internal document sequence number.
v Merge Conflicts -- If a replication conflict occurs, 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. The main
document is selected based on the criteria listed in the bullet above.
v Merge/No Conflicts -- If replication occurs, saves the edits to each field in a single document. If two
users edit the same field in the same document, Notes selects the field from the main document, based
on time and date, and an internal document sequence number. No conflict document is generated,
instead conflicting documents are merged into a single document at the field level.
v Do Not Create Conflicts -- No merge occurs. Domino simply chooses one document over another. The
other document is lost.

For more information on replication conflicts, see Lotus Notes Help.

Opening documents in edit mode automatically


For users’ convenience, you can specify that documents created with a form automatically open in Edit
mode.

On the Defaults tab, select ″On Open: Automatically enable Edit Mode.″

Chapter 5. Designing forms 83


Choosing a content type for Web access
If the application you are designing will be accessible from a browser, consider what content type to
make available to browser users. The ″On Web Access″ section of the Default page of the Forms
properties box lets you choose between Notes, HTML, or Other. Displaying a form as a Notes form will
pass along the form to the Web server, which will translate it into HTML. If you have designed the form
using HTML you can set the content to serve the HTMl directly to the browser. If you choose Other,
Designer displays an edit control that lets you specify another display option, such as XML.

Generating HTML for hidden fields


On the Defaults tab of the Form Properties box, select ″Generate HTML for all fields″ to generate HTML
information about hidden fields on a form. This allows documents in a Web application to work like
documents in a Notes application. For example, if you create a form that relies on a hidden field for a
calculation, that form may not behave as expected in a Web application in certain situations. By
generating HTML for the fields, the information is available for Domino to successfully complete the
calculation. The HTML generated for the hidden fields is also accessible through JavaScript, so you can
change the value or find out the state of a hidden field with a script.

Selecting this option creates larger files on the Web and may decrease application performance. Also
consider security, since information in hidden fields, though not visible in the browser, is visible through
the ″View Source″ menu item on the browser.

On the Defaults tab, in the ″On Web Access″ section, check the option ″Generate HTML for all fields″ and
deselect HTML in the Content type section.

Using data sources on a form


If you have already created data connection resources in the database, you can browse for data resources
to use on the form.
1. On the Defaults tab of the Form Properties box, click the Browse button in the ″Data Source Options″
section. A ″Browse External Data Sources″ dialog box appears with a list of data connections resources
already created in the database.
2. Select a data connection resource and click OK. The resource populates the ″Default data connection″
field on the Defaults tab of the Form Properties box. The ″Default metadata object″ can be either a
backend database table, a view, or a procedure.

Once the user starts to create fields on the form using an external data resource, the default metadata
object can be changed.

To define a header on a form


If you are designing a form for a Notes application, you can define a header that does not scroll off the
screen when the user scrolls down the form or document created with that form. For example, in the
Notes mail template, a header displays all of the information contained in the mail sender and recipient
fields. This section remains static while you scroll through a mail message. Headers can contain any
element that a form can contain. The only caveat is that a table cannot be the first element in a header; it
must be preceded by a text object, even if the text object is blank.
1. Enter the text, graphics, tables, or other elements you want in the header region of the form.
2. Move the cursor to the line below where you want the header to start.
3. Choose Design - Form Properties.
4. On the Header tab select ″Add header to form″ to mark off the header area.
5. Set the display properties for the header.
v Height can be set in pixels or as a percentage of the form height. You can choose ″Fit to content,″
which set the heights automatically depending on the contents.

84 Application Development with Domino Designer 7


v Select a scrolling option. Auto automatically turns scrolling on when the content of the header
exceeds the space allotted.
v ″Allow resizing″ lets users reissue the header area. You can choose this option only when the
border width is greater than 0.
v Border controls the display of the dividing line between the header and the body of the form. You
can change the thickness of the line and the color of the border. You can turn the border off by
setting the width to 0. Select ″3D shading″ to show the border with a 3D effect.

To display a graphic in a header


To display a graphic in a header, add a background graphic to the form. This becomes the background
for the header only. Note that if you do this, the remainder of the form is blank and cannot display
another background graphic.

If you want the user who creates a document to be able to add a graphic to the body of the document
when it is created, check ″Allow users to change these properties″ at the Form Background tab of the
Form Properties box.

To create a print header and footer


You can define a header and footer that will print on all documents created with that form. Headers and
footers are not supported for Web applications.
1. On the Printing tab, click Header and enter the text you want to appear in the header text or click
Footer and enter the text you want to appear in the footer text.
2. Click one or more of the icons (located just below the text area) to insert the following into the header
or footer:
v Page number (first icon on the left)
v Date
v Time
v Tab
v Title (last icon on the right)
3. (Optional) Assign a font, size, and style for header or footer text.

Header and footer alignment


Headers and footers have three preset, permanent tab stops: left, center, and right. When you insert one
tab, text to the left of the tab is left justified, and text to its right is right justified. With two tabs, text to
the left of the first tab is left justified; text between the two tabs is centered; and text to the right of the
second tab is right justified. For example:

&D|&T|&P-- Left justifies the date, centers the time, and right justifies the page number.

|URGENT| -- Centers the text URGENT.

||URGENT -- Right justifies the text URGENT.

Creating a response hierarchy


If you are creating an application in which users can post responses to a main document, and responses
to the responses, you need to set up a hierarchy between the forms. There are three types of forms you
can designate:
v Document form -- The top level in a hierarchy of forms. It is often called the Main topic form and can
have zero or more response forms associated with it. A form creates main (parent) documents unless
you designate it as a form that creates response documents.

Chapter 5. Designing forms 85


v Response form -- Creates response documents associated with a main document. In a view, users select
a main document and then compose a response. The response documents appear under the main
document. Designers often create response documents that inherit data from the main document -- for
example, the topic title.
v Response-to-response form -- Creates response documents associated with either a main document or a
response document.
For information on indenting a response document under its parent document in a view, see the topic
″Indenting response documents″ in the chapter ″Designing Views.″

To create a response or response-to-response form


1. Open a form.
2. Choose Design - Form Properties.
3. On the Form Info tab, choose one of the following form types:
v Select ″Response″ for the form used to create responses to main documents.
v Select ″Response to Response″ for the form used to create responses to other responses.

To include a parent document in a new document


To make it easy for users to find a related document, a document can include a parent or related
document as a link, as collapsible rich text, or as rich text. For example, a new response document can
include a link to its main document. A link takes up less disk space than a parent document because
Domino stores only a pointer to the document rather than a copy of the document.

When inheritance is enabled, the user selects a document and then chooses Create - <response/new form
name>. The selected document becomes the parent document. The documents do not need a main
document/response document relationship, because the selected document is assumed to be the parent
document. A user can suppress inheritance by pressing CTRL while choosing Create.
1. Open the form.
2. Create a new rich text field to display the document or link.
3. Choose Design - Form Properties.
4. Click the Defaults tab.
5. Select ″On Create: Inherit entire selected document into rich text field.″
6. Select or enter the name of the rich text field you created in Step 2.
7. Select one of the following:
v Link
v Collapsible rich text
v Rich text
8. (Optional) Select ″On Open: Show context pane″ and Parent.

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

To designate a form for version tracking


1. Open the form.
2. Choose Design - Form Properties.

86 Application Development with Domino Designer 7


3. On the Form Info tab, select one of the following versioning methods, as follows:

Versioning method Description


New versions become responses Use this when the original document is the most important. The original
document is listed first in the view; all successive versions follow. Choose
this method if the original document is the focal point of the view, with
responses being used for reference.

When new versions become responses, you can prevent replication or save
conflicts in the view. If users on different servers modify and save the
main document, their versions are treated as two separate response
documents when the databases replicate. The two responses are displayed
in the view in chronological order.
Prior versions become responses Use this method 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 method 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 can’t prevent replication or


save conflicts. If users on different servers modify and save the main
document, the two new versions of the document appear as conflicting
main documents when the databases replicate.
New versions become siblings Use this method when all versions have equal importance. The original
document is listed first in the view; all successive version follow as
additional main documents without introducing the risk of replication or
save conflicts.

This method is also useful when revisions aren’t 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 don’t 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.

4. Then select one of the following ″Create versions choices″:

″Create versions″ choices Description


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

Make sure users know that version tracking is active, so that they understand the impact of editing
documents. Explain version tracking in the ″Using Database″ document.

If there is a response hierarchy set up in the database, responses to version-controlled documents display
as responses to the original document only.

Chapter 5. Designing forms 87


Customizing a form’s window title
The window title is the text that appears in the title bar when you compose, read, or edit a document. By
default, the word ″Untitled″ appears in the title bar. To help users understand the context of the
document they’re reading, create a descriptive window title.

A window title can be static -- that is, it always displays the same message -- or dynamic -- that is, it
displays a message that changes based on a formula you create. An example of a dynamic window title is
a title for a main document in a discussion database that includes the number of responses to the
document. The title changes each time a new response gets created.

To create a window title, 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 or
rich text lite. If the field does not contain text or if a function does not return text, you must convert the
value to text using the @Text function. For example, the following formula converts the date value in the
DateCreated field to a text value for display in the window title:
"Response created on " + @Text(DateCreated);

To customize a form’s window title


1. Open the form.
2. On the Object tab in the Programmer’s pane, select Window Title - attribute.
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. To test the window title, create, save, and read a new document. Make sure the title is appropriate for
all three situations.
For more information on creating window title formulas, see the Domino Designer Programming Guide.

Examples: Customizing window titles


Title includes creation date and company name
This formula displays the date the document was created, form name, and company that was billed.
@Text converts the date to a text string, and the extra spaces within the quotation marks force the words
in the title to be properly spaced.
@Text(@created) + " Inventory Invoice for " + CompanyName

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

Title includes number of responses


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

If the document has never been saved, New Topic shows in the title bar while the user composes the
document. After the document is saved, the title is the subject combined with the number of responses. If
the subject is Icebox 2000 and there are no responses, the title of the document is Icebox 2000 (No
Responses). With one response, the title becomes Icebox 2000 (1 Response). With two responses, the title
becomes Icebox 2000 (2 Responses).

Response includes the subject


When the response or response-to-response is first composed, this formula displays New Response To
and the subject of the main document.

88 Application Development with Domino Designer 7


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

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

To create a subform
You can copy and modify a subform that is similar to the one you need or create a new subform and
design it yourself.
1. Open the database that will have the new subform and click Shared Code - Subforms.
2. Click ″New Subform.″
3. Create the subform using the same elements you use to create a form.
4. Choose Design - Subform Properties. The Subform Properties box appears.
5. At the Subform Info tab, enter a name for the new subform.
6. Optionally, you can enter a comment.
7. Choose from the following options for displaying the subform:

Subform property Use


Include in Insert Subform dialog Lets designers see the subform name when inserting a subform.
Excluding a subform from the Insert Subform dialog box is not a
security measure. Users with Designer access or higher can open any
subform in Designer and copy individual components. Note that this
field does not apply to computed subforms.
Include in New Form dialog Check this if you want the subform to appear immediately when
designers choose Create - Design - Form. Note that this field does not
apply to computed subforms.
Render pass through HTML in Notes Lets you paste HTML directly into the subform. For more information
on pasting in HTML, see the topic ″Using HTML on a page or form″
in the ″Designing Pages″ chapter.
Do not add field names to field index Check this setting to prevent new field names on the subform from
being saved in the field index. Checking this setting saves memory.

If you do not check this setting, field names are saved to a table and
then stored in memory. Storing field names in memory allows field
names to appear in places such as the ″Add Action″ dialog box.

8. Close and save the subform.

Chapter 5. Designing forms 89


To insert a subform on a form
1. Open a form.
2. Place the cursor where you want to paste the subform.
3. Choose Create - Resource - Insert Subform. The Insert Subform dialog box appears.
4. Select the subform you want and click OK. You can also insert subforms contained in other databases
by selecting a database listed in the Database pull-down list.

To display a computed subform on a form


1. Open a form.
2. Place the cursor where you want to paste the subform.
3. Choose Create - Resource - Insert Subform.
4. Select ″Insert Subform based on formula.″
5. Click OK.
6. Enter a formula in the Programmer’s pane that determines which subform to display.
7. Close, name, and save the form.

Example of displaying a computed subform


In the Main Topic form of a discussion database, you want to display the NewDocSubform when a
document is created and the SavedDocSubform when a saved document is opened. Each subform
contains different fields and graphics. The Insert Subform formula is:
@If(@IsNewDoc;"NewDocSubform";"SavedDocSubform");

Note: Subform formulas cannot be refreshed while the document is open.

Deleting subforms
When a user opens a document that references a deleted subform, the message ″Subform: <subform
name> not loaded″ appears on the status bar. The document opens without any representation of the
deleted subform. When a designer opens a form that references a deleted subform, the message
″Subform: <subform name> not loaded″ appears on the status bar. When a designer clicks the deleted
subform area on the form, the message ″Invalid or nonexistent document″ appears and the designer can’t
open the subform.

To avoid these messages, add another subform to the database and give it the same name as the deleted
one.

To delete a subform from a form


You can remove a subform from an individual form, without disturbing other forms that use it.
1. Click the subform area on a form.
2. Choose Edit - Delete.
3. Adjust the formatting if necessary.

To delete a subform from a database


You can remove all instances of a subform from a database. Be aware that this will cause errors in any
form that refers to the subform.
1. Click Subforms in the design list for the database.
2. Choose Edit - Delete.

90 Application Development with Domino Designer 7


Layout regions
A layout region is a fixed-length design area on a form or subform. The advantage of using layout
regions is that related elements can be dragged and moved easily and can be displayed in ways not
possible on regular forms and subforms. A layout region can contain static text, graphics, buttons, and all
fields except rich text fields. You can hide or collapse a layout region and all its components under
certain conditions.

Layout regions are not supported in Web applications.

A layout region can contain:


v Text
v Background graphics
v Fields (except for the following fields: color, dialog list, formula, password, rich text, rich text lite, and
time zone)
v Buttons
v Button graphics

You should not add the following elements to a layout region:


v Animated GIF files
v Attachments
v Computed text
v Embedded elements
v Horizontal rules
v Hotspots
v Image resources
v Inserted resources
v Java applets
v Layers
v Links
v Objects
v OLE objects
v Page breaks
v Pop-ups
v Sections
v Shared actions
v Shared fields
v Subforms
v 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.

Creating a layout region


To create a layout region
1. Open the form.
2. Move the cursor to the location in the form where you want to place the layout region.

Chapter 5. Designing forms 91


3. Choose Create - Layout Region - New Layout Region.

To delete a layout region


1. Click the layout region and choose Edit - Delete.
2. Adjust the formatting if necessary.

Aligning and rearranging elements in a layout region


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

Changing the size and style of a layout region


You can adjust the size, position, and look of a layout region.
1. Open a form.
2. Click the layout region and choose Design - Layout Properties.
3. Select a different Left setting to move the layout region horizontally. Elements within the layout
region stay in a fixed position, relative to the borders of the layout region.
4. Select a different Width or Height setting to size the layout region perimeter.
5. Check ″Show border″ to make the layout region borders visible. To make the borders invisible,
uncheck this field.
6. Check ″3D style″ to show the layout region in gray and to show fields and buttons as they look in
dialog boxes.
7. Check ″Wrap text around region″ to have text in the form wrap around the layout region. The default
is to have text appear above the layout region.
8. Click ″Show grid″ to see the current spacing between elements.
9. (Optional) Do one or more of the following to align and rearrange elements:
v Click ″Snap to grid″ to align all elements with the grid.
v Change the grid size if you want a narrower or wider arrangement of elements.

Adding graphics to a layout region


1. Click on the layout region to select it.
2. Choose Create - Picture and select the graphic file.
3. Select either Graphic or Graphic Button. The graphic file is pasted into the center of the layout region.
You can move the graphic by dragging and dropping.
4. To change the left and top position of the graphic, select the graphic and choose Design - Object
Properties. The Control Properties box appears.
5. (Optional) Click the Hide tab of the Control Properties box to adjust the hide properties.
6. (Optional) Choose Design - Send to Back to position the graphic behind other elements.

92 Application Development with Domino Designer 7


Adding graphic buttons to a layout region
A graphic button adds a hotspot to a layout region.
1. Copy a graphic to the clipboard.
2. Click on the layout region to select it.
3. Choose Create - Layout Region - Graphic Button.
4. The graphic file is pasted into the center of the layout region. You can move the graphic by dragging
and dropping.
5. From the Objects tab on the Info List in the Programmer’s pane, select Hotspot - Click.
6. In the Script area of the Programmer’s pane, enter a formula for what you want the hotspot to do.
7. To change the left and top position of the graphic, select the graphic and choose Design - Object
Properties. The Control Properties box appears.
8. (Optional) Click the Hide tab of the Control Properties box to adjust the hide properties.
9. (Optional) Choose Design - Send to Back to position the graphic behind other elements.

Embedded controls
There are three types of embedded controls that can only be used on a form:
v The embedded file upload control -- Allows you to create a form so that Web users can attach files to
documents
v The embedded scheduler -- Allows you to create a form that displays the schedules of specified users
v The embedded editor -- Allows you to embed one or more forms into an existing form and can also
allow you to link an embedded editor to an embedded view.

Creating an embedded file upload control


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

Creating an embedded scheduler


The embedded scheduler allows you to design a form or subform that displays the schedules of users.
For example, you can create a form for users to schedule department meetings. Embedding a scheduler
on the form lets users check everyone’s schedules before planning the meeting time. Also, within the
embedded scheduler users can click on a person’s name to open that person’s calendar view (provided
the user has been given access in the person’s mail preferences). You can program the calendar to open in
a separate frame, or in its own window. For an example of an embedded scheduler form, see the Group
Calendar form in the Mail template.

There are four parts to using an embedded scheduler:


v Create an embedded scheduler on a form or subform (Create - Embedded Element - Scheduler).
v Create the fields that collect the data needed to display the embedded scheduler.
v Program the embedded scheduler to retrieve the data from the fields.
v Set properties for the embedded scheduler.

Chapter 5. Designing forms 93


To create an embedded scheduler on a form or subform
You can embed one or more embedded schedulers on a form or subform.
1. Open or create a form or subform for the embedded scheduler.
2. Move the cursor where you want the embedded scheduler to appear.
3. Choose Create - Embedded Element - Scheduler.

Note: The embedded scheduler does not display scheduling information while you are designing the
form or subform.

To create fields for the embedded scheduler


The embedded scheduler needs three pieces of information before it can display anyone’s schedule.
v Whose schedule to display (individuals or group).
v What week to start the schedule information from.
v How many hours per day of schedule information to display.

One way to collect this data is to create editable fields on the form and have users enter in those fields
the information they want displayed. You can also use LotusScript or the Formula language to create the
field items. For an example of collecting the data using an action button and Formula language, look at
the GroupScheduler form in the Mail Template.

Once you have created the fields or other method for collecting the data, you must associate those fields
with the Embedded Scheduler attributes, as described in the following section.

To program the embedded scheduler


Once you have created the fields for collecting the data, you must program the embedded scheduler so
that it can retrieve the data from the fields. You can program the embedded scheduler using the
following attributes.

To associate the fields with the attributes:


1. Select the attribute from Objects tab of the Info List and
2. Enter a field name in quotation marks in the Script area of the Programmer’s Pane.

Attribute Description
Required people items A formula that evaluates to a text list of one or more item names. At runtime, the
scheduler displays the set of required people.

If you are writing a LotusScript formula to obtain the data for this attribute, the formula
must evaluate to a text list of one or more field names.
Optional people items A formula that evaluates to a text list of one or more item names. At runtime, the
scheduler displays the set of optional people.
Rooms items A formula that evaluates to a text list of one or more item names. At runtime, the
scheduler displays the set of rooms.
Resources items A formula that evaluates to a text list of one or more item names. At runtime, the
scheduler displays the set of resource rooms.
Interval start time A formula that evaluates to an item name. At runtime, the time/date value contained in
this item indicates the start date/time of the meeting.
Interval end time A formula that evaluates to an item name. At runtime, the time/date value contained in
this item indicates the end date/time of the meeting.

94 Application Development with Domino Designer 7


Attribute Description
Grid Start time A formula that evaluates to an item name. If this attribute is not specified, the scheduler’s
busy time grid begins on the current time and date. If the event is specified, the
time/date value contained in this item is examined.

If the time portion of the time/date value is set to ALLDAY, the busy time grid uses the
specified date and the current time. If the date portion of the time/date value is set to
ANYDAY, the busy time grid uses the current date and the specified time.

The value of this field should be a date and time. If the value is not a date and time, the
current date and time of the user’s system is the default. If the value is a date only, that
date and the current time on the user’s system are the default. If the value is a time only,
that time and the current date on the user’s system are the default.

When a user accesses the form, the scheduling information starts from the specified date.
The user can change which week is displayed by clicking on the left and right arrow
keys. Each day will begin at the specified time. The time is rounded down to the nearest
hour.

Note that the schedules are displayed in terms of the user’s local time zone -- for
example, a Pacific time zone user free between 9 and 5 PST will appear free between 12
and 8 to an EST user.
Display hours per day A formula that evaluates to an item name. At runtime, the number value contained in
this item indicates the number of hours that the busy time grid displays for each day.

This attribute is examined to determine how many hours of each person’s schedule to
display. The value of this field should be an integer between 1 and 24, inclusive. A value
less than 1 will be defaulted to 1 and a value greater than 24 will be defaulted to 12.
Schedule Detail items A formula that evaluates to a text list of one or more item names. When the scheduler
retrieves scheduling data, detailed data is requested for these items.

Displaying a legend
You can create a reserved field on the form that contains the embedded scheduler to allow users to turn
the legend off or on. The reserved field name is $GroupScheduleShowLegend. Valid values are 0 (to turn
the legend off), and 1 (to display the legend).

To set properties for the embedded scheduler


1. Open the Embedded Scheduler Properties box.
2. At the Info tab, you can set any of the following properties for the embedded scheduler:
v Name -- Name of the scheduling element. This is the name used to obtain a LotusScript object for
this scheduler control.
v Target frame -- Specify the frame in which to display the group members’ calendar views and
appointment documents.
v Show interval indicator -- Indicates whether or not to display the appointment indicator (the
appointment indicator is one you can drag).
v Show color legend -- Checking this displays the busy time color legend.
v Show twisties -- Checking this displays twistie icons for required and optional people, allowing the
user to collapse and expand the required and optional list of people.
v Initialize from item values -- Checking this causes the scheduler control initially to determine which
participants to display based on the values of the items previously specified (see the preceding
attributes table ). You may want to uncheck this field for R5 backward compatibility with group
calendars.
v Refresh from item values -- Checking this causes the scheduler control to refresh data from the
values of the items previously specified. When a DocRecalc event occurs and this attribute is
checked, the scheduler control discards any participant data it has and generates a new list of

Chapter 5. Designing forms 95


participants from the values of the items on the form. It also updates the meeting start and end
times as well as the hours to display and the display start time. Because problems may occur when
the NotesUIScheduler object has been used to add or remove participants, you may want to disable
this field if a call to AddAttendee or RemoveAttendee is made through the NotesUIScheduler
object.
v Allow filtering -- Checking this field turns on the filtering button that is displayed above the
attendee names.
v Top, Middle, and Bottom titles -- Lets you specify titles for the top, middle, and bottom of the
embedded scheduler. You can click the formula symbol for each title and enter a formula that
evaluates to a title.
3. At the Colors tab of the Embedded Scheduler Properties box, you can customize various foreground
and background colors.
4. At the Layout tab of the Embedded Scheduler Properties box, you can set the width and height
properties for the embedded scheduler.

Creating an embedded editor


You can embed an editor into a form. One use of the embedded editor is to let you embed one or more
forms into an existing form. Another use of the embedded editor is targeting in which you link an
embedded editor to an embedded view. Targeting allows the user to edit documents in a view without
having to open separate windows.

You can do almost everything in an embedded editor that you can do in a document. However, you
cannot include the following in an embedded editor: buttons, action hotspots, formula popup hotspots,
computed text, or navigators. Note also that you should not use embedded editors in animated tables.

To create an embedded editor


1. Create a form or open an existing form.
2. In the form, place the cursor where you want to create the embedded editor.
3. Choose Create - Embedded Element - Editor. The Insert Embedded Form dialog box appears.
4. Choose one of the following options:
v None
This is the first choice under ″Choose a form.″ Choose None if you want to paste a document or
anchor link into the embedded editor or if you want to use targeting by linking an embedded
editor to an embedded view.
v An existing form from the list of forms
The list of forms in the current database appears under ″Choose a form.″ To insert an existing form
into the embedded editor, choose one of the forms.
To insert a form from another database, select a database from the pull-down list of databases and
then choose a form listed under ″Choose a form.″
v Insert form based on formula
To insert a form based on a formula, check ″Insert form based on formula.″
5. Choose Element - Editor Properties to open the Embedded Editor Properties box. Click the Info tab,
and then set any of the following properties:
v Name - enter a name for the embedded editor. Entering a name is necessary only if you are
targeting to an embedded view.
v Size - enter a size in inches for the width and height of the embedded editor. Alternately, you can
check ″Fit to window″ for the width and for the height.
v Type and Value - these fields are automatically filled out, depending on how the editor is created.
The following values may appear:
- Link

96 Application Development with Domino Designer 7


Link appears in the Type field if you selected None in the ″Insert Embedded Form″ dialog box. The
field next to the Type field and the Value field are both left blank.
Link requires that you paste a link that you’ve already copied to the Clipboard. Click the Paste icon
to paste in this link. Note that you can paste only an anchor or a document link. You cannot paste a
view or a database link.
- Named Element
Named Element appears if you selected an existing form in the Insert Embedded Form″ dialog box.
The field next to ″Named Element″ displays as Form. The Value field contains the name of the form
you chose in the Insert Embedded Form dialog box.
v Hide action bar - selecting this causes the action bar of the form you inserted to be hidden. If it is
unchecked, the action bar is displayed.
v Disable scroll bars - selecting this hides scroll bars. If it is deselected, the embedded editor shows
scroll bars when all of its content does not fit on the screen.

To use an embedded editor for targeting


You can place one or more embedded views on a form and then link them to one or more embedded
editors. This feature, called targeting, allows users to edit documents in a view without having to open
separate windows.
1. Create a new form.
2. Choose Create - Embedded Element - Editor.
3. Select None in the Insert Embedded Form dialog box and click OK.
4. Choose Element - Editor Properties. The Embedded Editor Properties box opens.
5. Specify a name for the embedded editor and close the properties box.
6. Choose Create - Embedded Element - View. The Insert Embedded View properties box appears.
7. Choose a view and click OK.
8. Choose Element - View Properties. The Embedded View Properties box opens.
9. In the ″Target Frame″ (for single click) field, enter the name of the embedded editor that you want to
link to. Close the properties box.
10. Save and close the new form.
11. Create a new document with the form.
12. Highlight a document in the embedded view. The document opens in the embedded editor. You can
now edit that document in the embedded editor. You can then switch to another document in the
embedded view and continue editing.

Profile forms
Profile forms are useful for collecting user-specific or database-specific values. These values are stored in
Profile documents. What sets profile documents from other documents is the way profile documents are
displayed and the values in the fields passed back. Only one profile document per form can exist for
each user of a database. Or, only one profile document can exist for a database if that form is available to
all users.

Profile documents allow for quick data retrieval, because they are cached while the database that stores
them is open. Profile documents are like other database documents except they are somewhat invisible --
they do not display in views and are not included in a document count for the database. Users create
profile documents by using an action button or agent you design that uses LotusScript or the formula
language.

A database can have a single profile document or multiple profile documents that match a key you
specify -- for example, an @username key that creates one profile document for each user of a database,
or a key that specifies a different profile document for each day of the week. Whether you use one profile
document for a database or use multiple profile documents depends on your design needs. Use a single

Chapter 5. Designing forms 97


profile document to contain settings that all documents in the database need, such as environment
variables. Use multiple profile documents for more customizable settings, such as user preferences. A user
must have at least Author access in the ACL of a database to create a profile document that is available to
all users.

You can use any form to create a profile document. After creating the form, you create a button, action, or
agent for the application that uses either @CommandEditProfile in a formula or UIWorkspace.EditProfile
or NotesDatabase GetProfileDocument in a LotusScript program to create or retrieve a document. In each
case, Notes looks for a profile document with the form name you specify, and creates a profile document
if one does not already exist. For an example of a profile document, see the Interest Profile form in the
Discussion - Notes & Web template.

For more information about accessing or editing a profile document using Formula language or
LotusScript, see the Domino Designer Programming Guide.

Creating a profile form


1. Create a form with fields to hold the values you want to store in profile documents.
2. Choose Design - Form Properties and deselect ″Include in Menu.″
3. Save the form.
4. Do not include the form in any view.
5. Create a button, action, or agent that uses either the LotusScript NotesDatabase GetProfileDocument
method or UIWorkspace.EditProfile, or the Formula language @Command([EditProfileDocument]) to
create or access the document.
See the Domino Designer Programming Guide for more information about Formula language and
LotusScript.

In Notes, you can create or edit a profile document by using @Command([EditProfileDocument]) or


@SetProfileField. In Web applications, use @SetProfileField to create profile documents. Note that
@Command([EditProfileDocument]) does not work on the Web.

You can use @SetProfileField and @GetProfileField to set and retrieve field values in profile documents in
both Notes and Web applications.

If you prefer scripts to formulas, use LotusScript routines to create and edit profile documents. The
EditProfile method of the NotesUIWorkspace class produces the same result as the
@Command([EditProfileDocument]) command used in a formula.

To set or retrieve field values for a profile document with a script, use the GetProfileDocument method to
access the document. You can then retrieve values from the document or set new ones, just as you would
with any document.

Use the IsProfile property for the NotesDocument class to determine if a NotesDocument object is a
profile document. Use the NameOfProfile property to retrieve the name of the profile document.

Note: You cannot delete a profile document using an @command or @function. Use LotusScript if you
must delete a profile document.

Forms that prompt users for input


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

98 Application Development with Domino Designer 7


Designing a form that presents a dialog box
To help users to fill out documents, create a custom dialog box that prompts for specific input. You can
do this by using the @DialogBox function or LotusScript. Using @DialogBox requires two forms: one, the
dialog form, has a layout region that contains fields, text, and graphics, and looks like a dialog box; the
other, the host form, contains a button that uses @DialogBox to display the dialog form. The two forms
contain shared fields, and when users enter field values in the dialog form, the values are shared with
fields on the host form that have the same names. For example, a host form called ″Memo″ has a button
that uses @DialogBox to bring up the dialog form called ″Memo Options.″ Both forms have a field called
″Comments.″ Text entered into the Comments field in the Memo Options form also appears in the
Comments field in the Memo document.

When you use @DialogBox, all values entered in the dialog box are stored in the document created with
the host form and can be seen in its Document Properties box even if the fields do not appear on the host
form. If the keyword [NoNewFields] is used with the @DialogBox function, the fields that are on both the
host form and the dialog form will be updated when the dialog form is saved or refreshed. If
[NoFieldUpdate] is used, no fields or field values from the dialog box form will be updated on the host
form.

Layout regions are supported in Notes applications only.


1. Open or create the dialog form.
2. Choose Create - Layout Region - New Layout Region.
3. Resize the layout region to fit the dialog box you want to create.
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. Place the cursor where you want to add the button, and choose Create - Hotspot - Button.
10. On the Display tab, add a label and width for the button.
11. In the Programmer’s pane, click Formula, and write a formula using @DialogBox. Include the name
of the dialog form.
For information on using @Dialogbox, see the Domino Designer Programming Guide.

Guidelines for designing a form that presents a dialog box


To match the Notes user interface as closely as possible, follow these guidelines:
v 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.
v In the @DialogBox formula, include the [AutoVertFit] and [AutoHorzFit] options to size the dialog box
to fit the layout region.
v Use 9 point Helvetica for static text, fields, and buttons.
v Place static text labels above or to the left of fields and end them with a colon (for example, Name:).
v Place buttons at the bottom of forms.
OK and Cancel buttons appear automatically to the right of the layout region. If you do not want the
cancel button to appear, use the @DialogBox keyword [NoCancel]. If you do not want the OK or the
Cancel button to appear use [NoOkCancel].
v To arrange choices horizontally, use the multi-column display option with radio button and check box
field; use None for the frame option so choices blend with the dialog box background.

Chapter 5. Designing forms 99


v For button text with multiple words, use initial capital letters. Use ellipses for buttons that lead to
another dialog box or task -- for example, ″Show Details...″

Designing a form that prompts users for information


You can design a form that uses @Prompt to request information from users to help them fill out a
document. This function is similar to @DialogBox, but it is simpler: @Prompt contains only text and
doesn’t interact with any other forms.
1. Create a form.
2. Create a button, hotspot, or action that will store the @Prompt formula.
3. Click the button, hotspot, or action.
4. In the Objects tab on the Info list in the Programmer’s pane, select the Click method for the button,
hotspot, or action.
5. In the Script area of the Programmer’s pane, enter an @Prompt formula.
6. Save and close the form.
For more information on @Prompt, see the Domino Designer Programming Guide.

Examples: Using @Prompt

[YesNoCancel]
This formula displays a warning before a memo is sent, giving users a chance to select Yes, No, or
Cancel.
Result := @Prompt([YesNoCancel]; "Send memo?"; "This memo will be sent to everyone listed in the
To, CC, and BCC fields." );

[OkCancelEdit]
This formula fills the Name field with the user’s response to the prompt. The default value is the user’s
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 user’s response in a temporary variable called ComposeType and uses it to
create a new report using the appropriate form.
ComposeType := @Prompt([OKCancelList]; "Report Type"; "Choose a report type."; "Adjustment Report";
"Adjustment Report":"Infant Progress Report":"Toddler Progress Report":"Preschool
Progress Report":"Transition to Kindergarten Report");
@Do(@Command([Compose]; ""; ComposeType));

Designing a form that lets users make selections from a view


You can design a form that uses @PickList to display a list of choices from a view.
1. Create a form.
2. Create a button, hotspot, or action to store the @PickList formula.
3. For an action, choose View - Action Pane and then click the action. For button or hotspot, click the
form and then click the button or hotspot.
4. In the Objects tab on the Info list in the Programmer’s pane, select the Click method for the button,
hotspot, or action.
5. In the Script area of the Programmer’s pane, make sure you have selected Run - Client - Formula.
6. Write a formula using @PickList and the [Custom] parameter, unless you want to use [Name] to
display a Domino directory or personal name and address book.
7. Close and save the form.

100 Application Development with Domino Designer 7


Using @PickList
The @PickList function looks up the values in a view as @DbColumn does, but lets the user pick a value
from one document. This function 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.
v It is not limited to 64K of data.
v It is faster than @DbColumn or @DbLookup.
v 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 Domino Designer Programming Guide.

Example
This formula displays the Products view of PROD.NSF in a dialog box:
choice:=@PickList([Custom] ; "":"prod.nsf" ; "Products" ; "Select a product" ; "Please select the
products you want to order" ; 1 );

Designing a form for a Domino billing application


Domino billing is a server function that tracks server usage. Domino billing tracks only the documents
that you specify. To specify the documents to track, you must add one or both of the following hidden
fields to the form that creates the documents.

Use this field To create a billing record when users


$ChargeRead Open a document that contains this field
$ChargeWrite Create, copy, edit, or save a document that contains this field

To specify which documents to track


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

Note: If there are many documents you want to track, you can create a shared field and add it to
multiple forms. If a database is updated by a template, you can modify the template to include the
hidden fields.

For more information on billing, see the Administering the Domino System.

Designing a form for contact printing


Contact printing is a type of printing in which users choose a form and a paper sectioning scheme to
print multiple documents. For example, you can print multiple names and addresses (listings) and choose
options for creating sections (such as twenty labels on a page). To make contact printing in an application
available to users, the designer must create and enable a form for contact printing.

Chapter 5. Designing forms 101


To create and enable a form for contact printing:
1. Create a form in Designer and define the layout and content of the form.
2. Choose Design - Form Properties.
3. At the Form Info tab, name the form and then check ″Include in Print″ to enable the form for contact
printing. It is recommended that you do not check other Display options.

Note: Checking ″Include in Print″ is the only way to enable a form for contact printing.
4. Close the Form Properties dialog box.
5. Create all the reserved fields listed in the table that follows these steps. Although you can place the
fields anywhere on the form, they are typically placed at the bottom of the form to separate them
from the main body of the form.
You can also create a subform containing some or all of the reserved fields and then insert the
subform into one or more forms.
All of the contact printing reserved fields are required. They must also have the same number of
entries in each, except for $SectDataOptions. If there is one entry, then the form has one sectioning
type (for example 20 labels to a page) available to it. If two entries, then the form has two sectioning
types (for example 20 or 30 labels to a page).
6. For each of the reserved fields:
At the Field Info tab:
v Next to Name, enter the reserved field name.
v Next to Type, select ″Text″ and then ″Computed.″
v Check ″Allow multiple values.″ Leave the next two settings unchecked.
At the Hide When tab:
v Check ″Printed″ in the ″Hide paragraph when document is″ section.
7. Close the Field Properties dialog box.
8. For each of the reserved fields, go to the Objects pane of the Programmer’s pane, find the name of the
field you just created, and select Value. Then, click in the Script area and enter the appropriate value.
Enclosed the value in quotes. See the following table for information on the values you can enter for
each reserved field.

Reserved Fields for Print


Listings
Reserved field name Description and values
$SectDataName Enter a name for the sectioning type and enclose it in quotes (for example, ″2 x 7
Labels, 1-1/3 x 4 in″). The name you enter as the value is the name shown for the
sectioning type (or Paper type) on the Documents Style tab of the ″Print view″
dialog box in Lotus Notes. This name also appears in form error messages.

The sectioning type can have multiple entries, but they must be separated by a
colon (for example, ″2 x 10 Labels, 1 x 4 in″ : ″3 x 10 Labels, 1 x 2-5/8 in″). If the
sectioning type has multiple entries, other contact printing reserved field (except for
$SectDataOptions) must have the same number of entries.

102 Application Development with Domino Designer 7


Reserved Fields for Print
Listings
$SectDataOptions Choose options for printing the listings or leave the value blank by specifying
double quotes with no characters between them (″″).

Separate multiple options with spaces (for example, ″Debug Inches″). Note that, for
this field only, you do not have to match the number of entries with the number in
other print listings reserved fields.

Only the following options are valid:


v Fullsheet -- Sectioning is turned off and the whole sheet of paper is taken to be
the section. The form still determines the content and layout of the listing
produced for each document. This option is useful for print merges. Usually,
print headers, print footers, and page settings are ignored in print listings;
however, the Fullsheet option prints normal print headers, print footers, and
page settings. If you specify the Fullsheet option, the next four reserved fields are
ignored.
v Debug -- Causes a rectangle to be drawn around the perimeter of each printed
section and around the inner margin of each printed section. You can use this
option to debug the data for a sectioning type because you can see on the
printed paper where each section prints and where the inner margin of each
section lies. This option also lets you preview the labels.
v Centimeters -- Causes the values in $SectDataWidthAndHeight,
$SectDataInnerMargins, and $SectDataOriginXandY, to be interpreted as 1/100th
of a centimeter rather than the default of 1/1000th of an inch. In other words,
this option turns on metric units.
v Inches -- Causes the values in $SectDataWidthAndHeight,
$SectDataInnerMargins, and $SectDataOriginXandY to be interpreted as 1/1000th
of an inch. This is the default. If both inches and centimeters appear in
$SectDataOptions values, the last one on the right takes precedence.
v Relaxrowsandcols -- Looks at the number of rows and columns specified in
$SectDataRowsAndCols and, if necessary, reduces the number of rows and
columns to what actually fits fully within the paper. If this option is not
specified, the number of rows and columns specified in $SectDataRowsAndCols
is taken literally, even if the specified number of rows or columns does not fit
within the paper.
$SectDataRowsAndCols The value in this field always contains two options separated by a space. For
example: ″7 2.″ The first option is the number of rows and the second is the
number of columns. Both values must be 1 or greater. If you have two entries for
other fields, you must have two entries here. For example: ″10 2″ : ″10 3″
Note: For this field (and the remaining reserved fields):
v If fewer options are given than the item requires, the remaining options are
interpreted to be zero (″0″). If no options are specified, ″0″ is assumed for all
options. If extra options are specified, they are ignored.
v For a sectioning scheme where there is only one section per sheet of paper,
specify ″1 1.″ If you have specified the Fullsheet option, enter an empty value in
double quotes (″″).
$SectDataWidthAndHeight Specifies the width and height of each section. The value in this field takes two
options. The first option gives the width of one section and the second option gives
the height (for example: ″4156 1000″). Both values are in 1/1000th of an inch. For
example, 1-1/2 inch would be written 1500. The value must be one or greater.

If you have two entries in other fields, there must be two entries in this field (for
example : ″4156 1000″ : ″2781 1000″).

Chapter 5. Designing forms 103


Reserved Fields for Print
Listings
$SectDataInnerMargins Specifies an inner margin for each section. The value in this field must contain four
numbers, separated by spaces, and specifies an inner margin for each section. In
order, the options are left, right, top, and bottom margins (for example: ″156 0 0 0″).

The inner margins are measured inward from the section’s overall width and
height ($SectDataWidthAndHeight), within which the listing is placed. You can also
use the inner margins to avoid printing in preprinted areas and pre-punched holes.

You can enter any value including zero. The only restriction is that the sum of the
inner margins in each direction must not exceed the size of the section itself in that
direction. For example, you cannot specify a section width of 1.5 inches, a left inner
margin of 1 inch, and a right inner margin of 1 inch.

If you have two entries in other fields, you must have two entries in this field (for
example: ″156 0 0 0″:″156 0 0 0″).
$SectDataOriginXandY Specifies the exact location, measured from the upper left corner of the physical
page, for where the data begins on the page. The value for this field contains two
options. The first option gives the beginning horizontal position and the second
option gives the beginning vertical position (for example: ″100 835″). Both are in
1/1000th inch and any value including zero is valid. Remember that if you have
multiple entries in other fields, you must have multiple values in this field (for
example: ″100 835″:″100 835″).

The first option not only gives the location of the upper-leftmost section, but also
implicitly positions all other sections (because all sections abut each other with zero
pixel separation between each). The sections step horizontally by the
$SectDataWidthAndHeight width value and step vertically by the
$SectDataWidthAndHeight height value. The stepping proceeds through the
number of rows and columns given in $SectDataRowsAndCols. However, if you
previously specified Relaxrowsandcols, the stepping proceeds for as many rows
and columns as fully fit within the physical sheet of paper.

Be careful when you use zero as a value. For most printers, the printable portion of
the paper begins 1/8 to 1/4 inch inward from the upper left corner of the physical
paper.

Example
In Designer, you can view examples of contact printing forms and fields by opening your Lotus Notes
Personal Address Book (NAMES.NSF) and viewing forms such as ″Address labels 20 or 30, business.″

In Lotus Notes, you can see an example of how contact printing works for the end user:
1. From the Notes client, open the Personal Address Book (NAMES.NSF).
2. Choose the Contacts view.
3. Choose File - Print. The Print View dialog box appears.
4. At the Printer tab, click ″Selected documents.″ The Documents Style tab appears.
5. At the Document Styles tab, click ″Print multiple documents on each page.″
6. Next to ″Label format,″ you can view a list of the contact printing forms. For example, ″Address
labels 20 or 30, business″ is a form enabled for contact printing and was created using the contact
printing reserved fields.
7. Next to ″Paper type,″ you can view the values set by the contact printing reserved fields. For the
″Address labels 20 or 30, business″ form, you have two paper sectioning entries: ″2 x 10 Labels, 1 x 4
in″ or ″3 x 10 Labels, 1 x 2-5/8 in.″ (These two paper sectioning entries were specified in the
$SectDataName field.)

104 Application Development with Domino Designer 7


Customizing the ″Form processed″ confirmation for Web users
When Web users submit a document, Domino sends them the default confirmation message ″Form
processed.″ To change the default message, add a computed text field to the form, name it $$Return, and
use HTML as the computed value.

To add users’ names to the response


The following $$Return formula returns the response ″Thank you,″ and appends the user’s 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>");

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

To display a different Web 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]"

Displaying a customized error message on the Web


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 one of the following
names. Then create an editable text field named MessageString to hold the error message. Add additional
text, links, and other form objects that you want to display with the error message.

Form name Condition


$$ReturnAuthenticationFailure The user’s name and password cannot be verified.
$$ReturnAuthorizationFailure The user does not have a sufficient access level for the database.
$$ReturnDocumentDeleted A document was successfully deleted.
$$ReturnGeneralError Any other error condition has occurred.

Adding the message field


Create one of the following fields to hold the error message:
v An editable text field named MessageString to display the default server-generated error message.
v A computed-for-display field whose formula replaces the default error message with a customized
message.

Chapter 5. Designing forms 105


For example, this formula for a field named CustomString on a $$ReturnAuthenticationFailure form
gives more information to the user if authentication fails. The formula takes the value from the default
MessageString field if it contains ″unauthenticated″ and replaces it with instructions to the user. If the
MessageString field does not contain the word ″unauthenticated″, Domino uses the value of
MessageString instead.
@If(@Contains(messagestring;"unauthenticated");"Sorry, the name and password you entered are unknown in
our system. If you are new to our site, return to the home page and follow instructions for registering.";
messagestring)

Customizing search forms


The Search utility lets users find information within a single application or an entire domain. You can
customize search forms to suit organization-specific needs. An application developer can, for example,
add a corporate logo to either form, or rearrange the fields.

You can also add custom forms to individual databases to customize Web searches within a single
database.

To customize the forms you can:


v Create a database based on the Catalog (R5.0) template on the Domino server you are using for
domain search.
v Copy the forms into the domain catalog database on the Domino server you are using for domain
search.

Customizing search input forms


For domain search, the Notes client uses the form named DomainQuery in the catalog server’s catalog.nsf
database as the search form. This form uses the FTDomainSearch method to implement the search. Web
domain searches can use any form through an OpenForm URL command and build and invoke a
SearchDomain URL command to perform the search, supplying arguments either as URL command
arguments or through posted field values.

Single database searches over the Web can be initiated using a $SearchForm?SearchView URL command.
In this case Domino looks in the current database for a form with the actual name or the alias name
$$Search. If the form exists, Domino opens it; otherwise, Domino displays a default search form based on
the search.h™ file stored in the Domino\Icons directory. The $$Search form builds and invokes a
SearchView URL command to perform the search, supplying arguments either as URL command
arguments or using posted field values. You can also customize the default search.h form.

Refer to the following table if you are customizing a search form for use on the Web. The table lists the
URL command arguments used to drive the initial search through the SearchDomain or SearchView URL.
These values are available on the results page for use by buttons and hotspots on the results form. For
example, you may specify &SearchOrder=2 on your initial search form. The field SearchOrder will have a
value of two in the results page. A Next button on the results form can use this value for the next page
or override it by specifying something else.

Although TRUE and FALSE can be specified for some of the fields, when the values are carried over onto
the results page they are 1 or 0.

Optional
arguments Description Default Value
Query The search string none

106 Application Development with Domino Designer 7


Optional
arguments Description Default Value
SearchMax Maximum number of entries to return in total; 0 = no None. Note that
limit
default and maximum SearchMax
values can be configured for the
Web server through settings in the
Domino Directory.
SearchWv Include word variants: TRUE or 1 or FALSE or 0 FALSE
SearchOrder 1 = by relevance 1

2 = by date ascending

3 = by date descending

4 = use view order (SearchView only)


SearchThesaurus Use thesaurus synonyms: TRUE or 1 or FALSE or 0 FALSE

(This option is ignored by the R5 search engine)


SearchFuzzy Use fuzzy search: TRUE or 1 or FALSE or 0 FALSE
SearchEntry Name of form to use for each result entry ″ResultEntry″

(for SearchDomain only)


Start Start document for paged results; 0 = unpaged 0
Count Number to return for paged results; 0 = unpaged 0
Scope Scope of search: 0

1 = notes databases only

2 = filesystem only

0 = both

If you are customizing search forms for Notes clients, you must use the FTDomainSearch method.

For more information about using the FTDomainSearch method, see the Domino Designer Programming
Guide.

Searching for Header Information (search by Date Created or Modified)


The ″Add Search″ button that appears beside the full text search entry area in agents lets you search for
documents ″by date created″ and ″by date modified″. To write such queries yourself for use with the
FTSearch method, you can use the following special item names:

Header Field Item name


CREATION DATE _CreationDate
REVISION DATE _RevisionDate
DB TITLE (domain index only) _Title
DB CATEGORIES (domain index only) DbCategories
NOTE TITLE _Note_Title
AUTHOR _Note_Author

For example, to find all documents created before 5 January 2000, use the following query:

Chapter 5. Designing forms 107


[_CreationDate] < 01/05/2000

There are no field names stored in the document; the dates actually come from the document’s header,
not from fields. So you can use these reserved names with any document, even though they won’t appear
among the field items in the Document Properties dialog.

There is no syntax corresponding to the search builder functions to find documents based on a difference
from today’s date, for example -- ″is in the last n days″. Your agent will have to supply actual dates at
runtime (which it can calculate by adjusting today’s date). Keep in mind that date formats vary based on
user settings, and you must use a format that matches the workstation or server that will evaluate the
query.

Customizing Domain search results forms


Field Name Description
DSCreationTime Creation time of a document
DSModifiedTime Modification time of a document
DSURL URL to document
DSDBTitle Database title
DSDocSummary Document summary
DSDocTitle Document title
DSDocAuthor Document author
DSScore Relevance score
DSSServer Name of the server that the document was indexed on
DSType ″0″ indicates a Notes document, ″1″ indicates an external or file system document

You can name your results form whatever you want and then specify your chosen name in the
SearchDomain URL or to the FTDomainSearch LotusScript call. The Web will look for a form named
$$SearchDomainTemplate if you don’t name one in the URL.

When designing or viewing a Domain Search results form, it can be helpful to know where the Domain
Indexer finds the titles that it displays in the results. The Indexer checks each document for the following
Notes fields or items, in the order they are listed here, to use to represent the document’s title: Title,
Subject, Headline, and Topic field; window title (as designated by the developer of that Domino
application); and view summary (using the default form and default view). If none of these items can be
found, the Domain Indexer displays ″Document has no title″ in the results.

In file systems such as Lotus SmartSuite® or Microsoft Office, the title and author are extracted from the
document properties fields. For HTML files, TITLE and AUTHOR tags are used.

How SearchResults and ResultEntry/DetailedResultEntry are used


The LotusScript below is attached to the click event of the Search action hotspot used by the Notes client
on the search form. The lines that call the name of the results form and the result entry form are bold.
Sub Click(Source As Button)
Dim s As New NotesSession
Dim db As NotesDatabase
Dim w As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Dim q As String
Dim l As Integer
Dim d As Integer
Dim sort As String
Dim stype As Integer

108 Application Development with Domino Designer 7


Dim useint As Integer
Dim rtype As String
Dim rformname As String
Set db=s.CurrentDatabase
Set uidoc = w.currentdocument
uidoc.refresh
Set doc=uidoc.Document

q=doc.query(0)
l=doc.resultlimit(0)
d=doc.MaxDisplay(0)
sort = doc.sort(0)
usestr = doc.use
sscope=doc.searchscope
rtype=doc.GetItemValue("SearchType")(0)

If rtype = "1" Then


rformname="DetailedResultEntry" Else
rformname="ResultEntry" End If
Select Case sort
Case "R" stype = FT_SCORES
Case "O" stype = FT_DATE_ASC
Case "N" stype = FT_DATE_DES
End Select

Forall values In usestr


If values = "2" Then useint = useint + FT_STEMS
If values = "3" Then useint = useint + FT_FUZZY
End Forall

Forall values In sscope


If values = "1" Then useint = useint + FT_DATABASE
If values = "2" Then useint = useint + FT_FILESYSTEM
End Forall

On Error Resume Next


If db.isopen Then
If Err <> 0 Then
Messagebox STR_DBOPEN_ERROR
Err = 0
Exit Sub
End If

Set srdoc = db.ftdomainsearch(q, l, stype,useint, 0,d,rformname) If Err <> 0 Then


Messagebox STR_FTERROR_PREFIX & Error$, 0 , STR_ERROR
Err=0
Exit Sub
End If
srdoc.Form="SearchResults" Call w.EditDocument(False, srdoc, True)
End If
End Sub

Tip: You must select the ″Generate HTML for all fields″ option in the Form properties box to preserve
field values when data is passed between a Web browser and the server.

Customizing Web SearchView results


To customize the Web Search Results page for SearchView:

Chapter 5. Designing forms 109


1. Create a form and assign it one of the form names shown in the following table.

Form name Field required Comments


$$SearchTemplate for $$ViewBody Associates the form with a specific view. Domino requires the
viewname $$ViewBody field, but ignores the value. The form name includes
viewname, 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 aren’t associated
with a specific form.

2. Add a field named $$ViewBody to the form.


3. If you want to display results page-by-page, add buttons or hotspots for forward and backward
navigation to the form.
4. Use the Start and Count parameters in your URL command.
For more information on URL commands, see the topic ″Programming options for Web applications″
in the appendix ″URL commands for Web applications.″

Using navigational buttons for paged results


To make it possible to navigate forward and backward between pages of results, add buttons or hotspots
to the SearchResults form. The fields available for use with next and previous buttons are listed in the
table below. In the Notes client, the buttons should reinvoke the LotusScript FTDomainSearch function
with revised arguments. On the Web, they should be used to construct a new SearchDomain URL to fetch
a new set of results.

Note: If you use editable fields on a search result form, select the option ″Web Access: Use JavaScript
when generating pages,″ in the Database properties. If selected, a URL attached to a hotspot or button
will be computed on the click event. If it is not selected, the URL will be computed when the page is
loaded.

Field Description
Query Search string used
Start Starting document number
Count Number of results requested for this page
Hits Actual number of results returned this page, which may be less than Count requested.
This field is useful in determining the Start parameter for a Next button.
TotalHits Total number of hits found by the search.
SearchMax Maximum number of entries to return in total; 0 = no limit.
SearchWv (only for URL Include word variants: 1 or 0.
command)
SearchOrder (only for URL 1 = by relevance 2 = by date ascending 3 = by date descending
command)
4 = use view order (SearchView only)
SearchThesaurus (only for Use thesaurus synonyms: 1 or 0.
URL command)
SearchFuzzy (only for URL Use fuzzy search: 1 or 0.
command)
SortOptions (only for Notes FT_SCORES = by relevance FT_DATE_ASC = by date ascending FT_DATE_DES = by
client) date descending

110 Application Development with Domino Designer 7


Field Description
OtherOptions (only for FT_STEMS = Include word variants FT_FUZZY = Use fuzzy search FT_DATABASE =
Notes client) search databases FT_FILESYSTEM = search file systems
SearchEntry (Domain Name of the result entry form used.
Searches only)
SearchView (only for Text unique identifier of the view being searched. This identifier is useful in building
SearchView URL command) subsequent SearchView URL commands.
Scope (only for Scope of search: 1 = notes databases only 2 = file system only 0 = both
SearchDomain URL
command)

The fields in the table below are available for use with the Start and Count parameters and should be
added to the results form as needed.

Field Description
Hits The actual number of hits returned. This field is useful in determining the Start
parameter of Next.
TotalHits The total number of hits found without regard to the number of pages.

Tips for improving document display time


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

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

Designing fields
v Use @DbColumn or @DbLookup formulas sparingly, or replace them with LotusScript programs which
are generally faster and support error checking.
v Use simple formulas for ″hide when″ conditions.
v Avoid recalculating fields, if possible. Otherwise, change such fields to computed-when-composed
fields. While these fields calculate only when the document is composed, they can be updated later if
needed through buttons, actions, or agents.
v 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″).
v Minimize the number of fields, especially hidden fields, and use form events rather than field formulas
to execute processing logic. You can avoid unnecessary recalculations in this way.
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, the field value is set only
when a document is saved, not when it is opened or refreshed.
For more information on writing lookup formulas, or ″hide-when″ formulas, see the Domino Designer
Programming Guide.

Chapter 5. Designing forms 111


Testing a form before deploying it
There are two ways to test a form before using it in the actual application. You can preview the form
from the Notes client or through a Web browser to see how it will look to a user and to make sure form
elements are working. In addition, you should test the form in the application by creating documents,
examining the documents through different views, and testing all actions.

If you are testing a response form or a response to response form, you should do one of the following:
v Select a document to respond to from the Notes Client in order to test the form.
v Deselect the type ″response″ or ″response to response″ on the Form Properties box until you have
thoroughly tested the form.
For more information on previewing your work, see the topic ″Previewing your design work″ in the
chapter ″Creating an application.″

112 Application Development with Domino Designer 7


Chapter 6. Designing fields
A field is the part of an application that collects data. You create fields on forms, subforms, or in layout
regions. Each field stores a single type of information. A field’s field type defines the kind of information
a field accepts, such as text, numbers, dates, or names. When a user, either in a Notes client or a Web
browser, creates a form, fills out the information in the fields, and saves the form, the data in the fields is
stored in an individual document. The contents of the fields can then be displayed in documents and
views or can be retrieved for use in formulas. A field can be used on a single form, or you can create
shared fields for use in multiple forms in a database.

You can create a single-use field on a single form, or a shared field to use on several forms. In either case,
you must specify the following:
v Field name
v Field type
v Whether this field is editable or computed

Creating a single-use field


When you create a field on a form, the field displays with its name surrounded by a rectangle and a
letter or symbol that lets you know what type of field it is. You can use tabs, returns, and other
formatting tools to refine the field’s position on the form.
1. Open the form.
2. Place the cursor over where you want the field to appear.
3. Choose Create - Field.
4. In the Field Properties box:
v Assign a name to the field.
v Assign a field type.
v Select the display style.
v Select Editable or one of the computed options.
5. On the Control tab, select a display option for the field.
6. On the Fonts tab, format the font style for the field.

To copy fields
If you copy a field from one place on a form to another, each copy of the field has a sequential number
appended to its name to preserve name uniqueness. You can rename the field after copying it.

Note: If you copy a shared field and paste it into the same form, the new field becomes a single-use
field. However, if you copy a shared field and paste it into a different form, the copied field remains a
shared field.

To delete fields
To delete a field, select the field on the form and press the Delete key, or choose Edit - Delete.

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.

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

To convert a shared field to a single-use field


To convert a shared field on a form to a single-use field on the form:
1. Open the form.
2. Click the shared field.
3. Choose Design - Convert To Single Use.

To convert a single-use field to a shared field


1. Open the form.
2. Click the field to be shared.
3. Choose Design – Share This Field.

Creating a shared field


You can define a field for use on more than one form. For example, many forms have a creation date
field, so you can define this field once and reuse it. When you define a field as a shared field, Designer
displays the field with a wider border than other fields and adds the field name to a list of shared fields
available for use in a database. To insert a shared field into another form in the database, 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.

To create a shared field


1. Expand Shared Code in the Design pane and click on Fields.
2. Click the button ″New Shared Field.″
3. Enter a name for the shared field.
4. Assign a field type and choose Editable or a computed option, if applicable.
5. Close the properties box.
6. Close and save the shared field.

To insert a shared field


1. Open a form and move the cursor to where you want the field to appear.
2. Choose Create - Resource - Insert Shared Field. The Insert Shared Field dialog box appears.
3. Select the shared field you want to use from the current database and click OK.
To select a shared field from another database, click the Database pull-down list, highlight a database,
select a shared field in that database, and click OK.
4. (Optional) Type a text label next to or above the field.
5. (Optional) Highlight the label and choose Text - Text Properties to change the text style.

To rename a shared field


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,

114 Application Development with Domino Designer 7


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.

To delete a shared field


To delete a shared field, you select the shared field from the list of shared fields and choose Edit - Delete.

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.

To convert a single-use field to a shared field


1. Open the form.
2. Click the field to be shared.
3. Choose Design – Share This Field.

To create multiple shared fields for different languages


If you have a multilingual database, you may want to create multiple copies of a shared field and target
each one for a different language. For example, you may want the help text for a shared field to be
different for different languages.

To create multiple shared fields for use in a multilingual database:


1. Make sure that the database containing the shared field is set up to be a multilingual database (File -
Database - Properties. At the Design tab, check ″Multilingual database.″)
2. In Designer, click Shared Code - Fields to display the list of shared fields.
3. Create the shared field you want to use in the multilingual database.
4. Depending on the number of languages, create multiple copies of this shared field by copying and
pasting the shared field. If the original field is named info, copies of the field are named info_1, info_2
and so on.
5. For each copy of the shared field:
v On the Shared Field Info tab of the Shared Field Properties box, set the name to be the same as the
name of the original shared field. (Note that Shared fields do not have aliases.)
v Make the necessary changes to the shared field. For example, if the selected language for that copy
of the shared field is to be French, you may want to enter a help description that is in French
(Advanced tab of the Shared Field Properties box).
v Close the Shared Field Properties box.
v Save and close the shared field.
v Select the shared field just edited and choose Design - Design Properties. The Design Properties box
appears.

Chapter 6. Designing fields 115


v On the Design tab, select a language for that version of the shared field. Depending on the
language you choose, you may also need to select a region for the selected language.
6. Repeat the previous step for each copy of the shared field and specify the appropriate language.

Field names and labels


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

Naming a field
A field name must begin with a letter and can include letters, numbers, and the symbols _ and $. The
name can contain up to 32 bytes. (If you’re 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.

Field names cannot contain spaces. Run multiple words together, for example, ModifiedDate, or separate
them with an underscore: Modified_Date. The Designer templates use the naming convention of an initial
capital letter followed by lowercase letters, for example, SendCopyTo.

If several fields on forms in a database contain similar information, for example, the date of creation and
the author’s name, use the same field name for all of them. This makes sharing information between
forms easier as you continue to develop the application. Establishing and maintaining naming standards
simplifies application design throughout your organization.

Renaming a field
Unlike forms and views that can have aliases, a field can have only one name. Renaming a field has the
same effect as deleting a field from a form. For example, if you have a field called ″Comments,″ and
users enter text into many instances of this field in documents, and you then rename the field to
″Observations,″ all of the data in ″Comments″ will no longer appear when you display the document. If
you must rename a field and need to transfer data, create a new field, create and run an agent to reassign
data to the new field, then delete the old field. Remember to update all formulas to refer to the new field
name.

Field types
The field’s field type determines what type of information it can contain. You define the field type in the
Field Properties box. The field types are:
v Authors
v Checkbox
v Color
v Combobox
v Date/Time
v Dialog List
v Formula
v Listbox
v Names
v Number
v Password
v Radio button
116 Application Development with Domino Designer 7
v Readers
v Rich text
v Rich text lite
v Text
v Time Zone

Text, rich text, and rich text lite fields


To collect, store, and display text in a field, create a text field, rich text field, or rich text lite field.
v Text fields generally suffice for data entry or text output in an application.
v Rich text fields are better for formatted text, large amounts of text, or embedding or attaching objects.
For example, the Subject field on a mail form is a text field, and the Body field is a rich text field.
v Rich text lite fields are rich text fields with a helper icon and down arrow next to the field. Clicking the
icon gives the user a fast way to add an object into the rich text lite field. Clicking the down arrow
displays a drop-down menu. The elements listed in the drop-down menu are the only elements the
user is allowed to insert into the rich text lite field. Any attempt to insert or paste an invalid element
into the rich text lite field displays an error message.

Rich text fields and rich text lite fields can be used anywhere except in a layout region. They are not
subject to the size limitations imposed on other field types.

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


Many databases use an editable, rich-text field named Body to give users the flexibility of adding
whatever they want to the main part of a document -- attachments, graphics, objects, or different fonts
and colors. A rich text field can contain anything a page contains.

Note: You cannot write to a rich text field by using simple actions or formulas. If you want to use simple
actions or formulas to write to a field, use text fields.

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

For more information, see the topic ″Launching objects automatically″ in the ″Designing Forms″ chapter.

Using rich text lite fields


To add a rich text lite field to a form, select rich text lite from the field type list (Field Info tab of the
Field Properties box). At the Control tab of the Field Properties box, check the object types you want to
add to the drop-down menu that appears when the user clicks the down arrow. Note that if you select
only one of these object types, no down arrow appears because there is no need to change types.

You can select or deselect one or more of the following object types (the object types selected have a
check next to them):
v Pictures
v Shared Images
v Attachments
v Views
v DatePicker
v Shared Applets
v Text
v OLE Objects

Chapter 6. Designing fields 117


v Calendar
v Inbox
v Links

Note: Links is a new type with Notes Designer 7.0. It allows links to documents, views, databases, and
URLs.

In addition, you can check the following options:


v Help - checking this lets the user choose to display brief help on an object type. The help changes
depending on the object type the user selects.
v Clear - checking this gives the user the option to clear the contents of the field.

At the ″First display″ field, select the object you want as the default icon when a document is first
created. For example, if a rich text lite field is limited to Pictures, DatePickers, and Shared Images, you
can choose to display Pictures as the first icon (indicating the intended use of the field while still giving
users the opportunity to add other types). If the user chooses another object type from the drop-down
menu, the icon changes.

The ″Field help″ field lets you add help for each object type. Note that you must enter help in the order
the fields are listed in the listbox. Also, you must separate each help text with the vertical bar character
(|). For example, to add help if you have selected pictures, shared images, and a datepicker, enter the
following in the Field Limit Help field:
Picture help|Shared Image help|||DatePicker help|

Note the extra vertical bar characters between Shared Image help and Date Picker help. These extra
characters indicate that no help text exists for attachments and views.

This is what happens when a user clicks on an icon next to the rich text lite field:
v For datepicker, inbox, and calendar, the object is inserted into the field immediately.
v For pictures, shared images, attachments, views, shared applets, text, and OLE objects, the
corresponding dialog box appears. Once the user selects from the choices in the dialog box, the object
is inserted into the field.

Rich text fields on the Web


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

Using the editor applet


Web users can do the following when using the editor applet in a rich text field:
v Bold, underline, and italicize text
v Change to Helvetica, Courier, or Times (fonts supported by the Java Development Kit (JDK), Release
1.0.2)
v Change font size
v Change font color
v Align paragraphs (left, center, right)
v Indent paragraphs
v Use bulleted and numbered lists
v Create links
v Cut, copy, and paste text within the rich text field

118 Application Development with Domino Designer 7


Note: Web users cannot paste text from outside the editor because of the limitations of the JDK,
Release 1.0.2.
v Enter international characters

Note: Not all international characters can be displayed in the editor applet. The ability to display
international characters depends on the fonts installed on the user’s workstation and the version of the
browser the user is working with. Most characters entered in the editor will be correctly transferred to
Domino (depending on the browser).

Enabling the editor applet


You can enable the editor applet in rich text fields only. To enable the editor applet:
1. Create or select a rich text field.
2. Choose Design - Field Properties.
3. On the Field Info tab, in the Web Access section, select ″Using Java Applet.″

When the editor becomes active, it displays as large as the Web browser’s window. It is recommended
that you resize it. The minimum size recommended is 300 by 500 pixels. To resize it:
1. In the Objects tab of the Info List in the Programmer’s pane, select the rich text field.
2. Click HTML Body Attributes.
3. In the Script area, enter the height and width. For example:
"HEIGHT=300 WIDTH=500"

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

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

Note: Make sure you test your design ahead of time on different browsers. Depending on the user’s
browser, there may be display problems.

Limitations of rich text fields on the Web


The following items may be lost or corrupted if they are in a rich text field which is edited with a Web
browser using Domino Web Server:
v embedded images -- may be visible when editing, but will be lost when the document is saved;
v tab tables - only the visible row will be saved;
v ″hide when″ paragraphs which are hidden from the Web -- the entire paragraph will be lost when the
document is saved.

Avoid using these items in a rich text field if that field is to be edited with a Web browser.

Chapter 6. Designing fields 119


Number fields
Use Number fields for numeric and currency data.

Numeric fields
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 don’t want users to change the value of a numeric field, select a Computed option in the Field
Properties box. In the example above, the Monthly Total field is computed so users cannot edit the value.

Fields used in calculations must have default values. Otherwise, the message ″Incorrect data type for
operator or @Function: Text expected″ appears.

On the Control tab of the Field Properties box, you can specify whether the field should display formats
according to the custom settings you specify, or whether it should use the default settings of the user’s
workstation.

Choose any of these number formats on the Control tab:


v Decimal displays numbers either as they are entered (zeroes to the right of the decimal point are
suppressed), or with a fixed number of decimal places, depending on what you specify. To base the
decimal symbol and thousands separator display on the type of measurement (Imperial or Metric)
users set in the operating system’s International User Preferences, choose Client. To set the decimal
symbol and thousands separator yourself, choose Custom.

Note: A number field can store up to 8 non-zero decimal digits without loss of precision. Notes
implements floating point arithmetic using the IEEE64 industry standard. In cases where a user enters
more than 8 non-zero decimal digits, rounding may occur and the number may display and be stored
differently from the number the user entered.
v Percent displays a number as a percentage. For example, .12 displays as 12% and 12 displays as 1200%.
v 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.
v Currency displays values with the currency symbol you specify. The default is the American dollar
sign. For example, $15.00 is displayed when the value is 15 and ″2″ is selected in the Decimal Places
list. You can select a different currency symbol from the list, or enter a custom currency symbol and
country code. See the next section for more on currency fields.

Designer recognizes the following formats for numbers:

Type Format
Integers 123, –123
Decimal fractions 1.23, 0.12, –.12
Scientific notation 1.23E2, –1.23E12
Currency $2.50, ($600.09)

Domino can store numbers from 2.225E–308 to 1.798E308 with 14–digit accuracy.

120 Application Development with Domino Designer 7


Currency fields
To choose currency as the type you want for the number field, check Currency at the Control tab of the
Fields Properties box. For currency, you may want different fields to display different currency formats
and you can do that at a field level.

If you want to use the currency defined in the user’s preferences, select ″Use preferences from: User
settings.″ If you want to define a custom currency, select ″Use preferences from: Custom.″

If you have selected ″Use preferences from: Custom,″ you have additional options in the ″Currency
symbol″ section of the Control tab. You can choose a currency symbol from an extensive pull-down list. If
you decide to check Custom, the currency you have chosen appears in the first box next to Custom (or
you can choose another currency symbol) and the country code associated with this currency appears in
the second box. You can then modify the country code. For example, the dollar sign ($) as a currency
symbol is used in many countries, including Canada, Jamaica, and the United States, and has different
values in each of these countries. For this reason, you may need to change the country code to one you
want to associate with this currency symbol. For a full list of countries and their ISO country codes, see
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html.

If the symbol you need is not included in the list, you can create a custom currency symbol by pasting in
the ASCII character for the currency symbol and then choosing a corresponding country code from the
pull-down list of country codes.

CAUTION:
Applying different currency formats, such as displaying British pounds in one field and American
dollars in another, might result in unexpected results if you combine values using the formula
language or a scripting language.

Date/Time fields
Date/Time fields display time and date information in a variety of formats. You can define a date or time
field as editable by the user, or you can choose a computed option so the user cannot change the field
value.

Dates may range from 1/1/0001 through 12/31/9999. Entering two-digit years between 00 and 49
assumes the century starting in the year 2000. Entering two-digit years between 50 and 99 assumes the
century starting in the year 1900. If you want users to enter a four-digit year in the field, on the Control
tab of the Field Properties box, select On input ″Require user to enter four digit years.″

Times may range from 00:00:00:00 through 23:59:59:59 in the 24–hour format and from 12:00:00 AM
through 11:59:59 PM in the 12–hour format.

Choosing a Date/Time format


On the Control tab of the Field properties box, you select the format for the display of the Date/Time
field. You can choose to use the date/time display based on the current user settings, or you can
customize the display.

To display a date
1. Select or create a Date/Time field.
2. On the Control tab, choose one of the following next to ″Use preferences from″:
v ″User setting″ to use the preferences from the user’s workstation.
v ″Custom″ to customize the display.

Chapter 6. Designing fields 121


Tip: If you are creating a custom Date/Time field, make sure to test your application with the user
preference ″Strict Date/Time Input″ checked and with it unchecked (File - Preferences - User
Preferences).
Also, if you are creating a custom Date/Time field, you may want to include field help text
(Advanced tab of the Field Properties box) to describe how the user should enter the date. You may
want to provide a brief example as part of the help text.
3. Check ″Display Date″ and then choose date options. As you select options, the sample will change to
show you what the user will see.
The following are the display date options:
Show:
v All
v Only month, day, and year
v Only weekday, month, and day
v Only month and year
v Only month and day
v Only year
v Only month
v Only day
v Only weekday
Special:
v Show ″today″ when appropriate
v Always show 4 digit year
v Show 4 digit year for the 21st century
Note that this setting takes precedence over 2-digit year formats chosen elsewhere in the Control
tab of the Field properties box.
v Show year only if not this year
Calendar:
v Gregorian calendar
v Hijri calendar
Format (appears if you selected Custom):
v YMDW - Year, month, day, weekday. For example, 98 12/17/Thu.
v WMDY - Weekday, month, day, year. For example, Thu 12/17/98.
v WDMY - Weekday, day, month, year. For example, Thu 17/12/98.
Separators (appears if you selected Custom):
v Enter the separators to use between the day, month, and year. For example, you can enter
backslashes (/) to present the date as 06/06/02.
Note that if you specify a comma as a date separator (for example: 11,15,98) then you must use a
semicolon if you are separating multiple dates in a list (for example: 11,15,98; 12,15,98; 1,15,99). If
you specify a semicolon as the date separator, then you must use a comma to separate multiple
values in the list.
Day, Month, Year, Weekday:
v Choose a format for the day, month, year, and weekday from the drop-down lists.

To display a time
1. Select or create a Date/Time field.
2. On the Control tab, choose one of the following from ″Use preferences from″:
v ″User setting″ to use the preferences from the user’s workstation.

122 Application Development with Domino Designer 7


v ″Custom″ to customize the display.
3. Check ″Display Time″ and then choose display time options. As you select options, the sample will
change to show you what the user will see.
The following are the display time options:
Show:
v All
v Hours, minutes, and seconds
v Hours and minutes
v Hours only
Time zone:
v Adjust time to local zone - Displays the time relative to the time zone in which the document was
created.
For example, if the document was created at 3:00 PM in Boston and is read by a user in Los
Angeles, the creation time is adjusted to the Pacific U.S. time zone and displays as 12:00 PM.
v 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 reader’s time zone; instead, Notes displays the
creator’s time zone. For example, if the document was created in Boston at 3:00 PM, the user in Los
Angeles sees the creation time as ″3:00 PM EST.″
v Show only if zone not local - Displays the zone in which the document was created only if the
document was created in a different time zone than it is being viewed in.
For example, if the document was created in Boston at 3:00 PM, users in the U.S. Eastern standard
time zone see the creation date as ″3:00 PM,″ while users in other time zones see the creation date
as ″3:00 PM EST.″
To take advantage of time zone options, note that the date must be included in the field.
Format (appears if you selected Custom):
v 12 hour
v 24 hour
Separator (appears if you selected Custom):
v Enter the separator to use between the hours, minutes, and seconds. For example, if you enter a
colon (:), the time appears as 11:52:35 AM.

To show both date and time together in the same field, select both ″Display Date″ and ″Display Time.″

Formulas for Date/Time fields


Dates and times are often calculated by formula rather than supplied by a user. Use the following
@functions to create date and time field values.

To display Create a Date/Time field showing Use the formula


Date a document was created Date and time @Created
Date a document was last modified Date and time @Modified
Date a document was last accessed Date and time @Accessed
Current date Date @Today
Current date and time Date and time @Now

Chapter 6. Designing fields 123


Creating a graphical display for Date/Time fields
You can display certain editable Date/Time fields either as a blank field that users type a date or time
into or as a graphical date/time control.

Note: Graphical date/time controls are not supported on the Web.

To create a calendar pop-up control


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

1. Create a Date/Time field that is editable.


2. On the Field Info tab of the Field Properties box, select ″Calendar/Time control.″
3. On the Control tab choose:
v On Display: ″Use preferences from User settings″
(Choose ″Use Preferences from Custom″ if you prefer to specify display options.)
v Display Date

To create a time control


Users can select time by clicking on the control and sliding the selection bar to a new time.

1. Create an editable Date/Time field.


2. On the Field Info tab of the Field Properties box, select ″Calendar/Time control.″

124 Application Development with Domino Designer 7


3. On the Control tab choose:
v On Display: ″Use preferences from User settings″
(Choose ″Use Preferences from Custom″ if you prefer to specify display options.)
v Display Time

To create a duration control


Users can select a range of time with a duration control, for example, from 12:00 PM - 1:00 PM.

1. Create an editable Date/Time field.


2. On the Field Info tab of the Field Properties box, select ″Allow multiple values″ and ″Native OS
Style.″
3. On the Control tab, choose:
v On Display: ″Use preferences from User settings″
(Choose ″Use Preferences from Custom″ if you prefer to specify display options.)
v Display Time

Names fields
Create a Names field to display user names. A Names field can be computed or editable. If you associate
the formula @UserName with a Names field, the name will appear the way it appears in Notes IDs -- for
example, Sara Ryan/Acme/US. If you enable online awareness for a Names field, users will see the
online status of Lotus Instant Messaging users listed in a Names field and can initiate an instant message
chat with an available user.

To display only the common name portion of names, use the [CN] parameters with @Name. For example,
in an editable names field called Members use this formula as the default value:
@Name([CN];Members)

This formula displays the name ″Sara Ryan″ if the user’s hierarchical name is Sara Ryan/Acme/US

For more information about formulas for displaying user names, see the formula language chapters in the
Domino Designer Programming Guide.

Chapter 6. Designing fields 125


Looking up names for field values
To help users enter names correctly in a document, provide links to existing lists of names. For example,
a Names field might require that users select names from the access control list for the database. This
enables users to pick a name from a list, eliminates spelling errors, and restricts names in the field. Other
sources for names are the Domino Directory or a view dialog that presents names from a column in a
view.

Lookup options are available on the Control tab of the Field Properties box when you create a Names
field, an Authors field, and a Readers field. You can turn off this option by maintaining the default choice
of ″none.″ If you select a lookup option for the field, users press CTRL+ENTER or click the entry helper
button to the right of the field to see a list of possible entries. Lookup options are not supported on the
Web.

Lookup options
v Use Address dialog for choices -- This option displays the Names dialog box so users can select names
from a Personal Address Book or Domino Directory. Select ″Look up names as each character is
entered″ to help users fill in a name quickly. Notes looks up a match for the typed letters in the open
Address Book or directory.
v Use Access Control List for choices -- This option brings up a list of people, servers, groups, and roles
in the access control list.
v 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 topic ″The database access control list″
in the chapter ″Security in an application.″

Enabling a field for instant messaging


You can enable a Names, Authors, or Readers field so that the field displays the online status of
Sametime users listed in the field. A Notes user viewing the document can click the name of an active
user and initiate a chat. For an example of this, see the Memo form of the Notes mail template.
1. Create a Names field, an Authors field, or a Readers field that evaluates to an abbreviated hierarchical
name. For example, Joe Allen/ACME/US.
2. On the Control tab of the Fields Properties box, check Show online status.
3. (Optional) Enter a Contact List Group label for the users listed in this field. You can enter a formula
that evaluates to a text string, or simply enter a text string in quotes -- for example ″Marketing Team.″
This group will be built dynamically when the document is opened and display at the top of your
contact list.

Note: This feature is not available for Web applications.

Tips
v You can use the same Contact List Group label for multiple fields on a document to build a group of
all the users listed in the fields. For example, you might want all of the users listed in the Reviewer
and Editor fields in a discussion application added to a single group named ″Project Team.″
v Users can see the online status icons for names that you enable for online awareness if the User
Preference ″Show Instant Messaging Status″ is enabled for their client. If this preference is disabled, a
user will need to click a name to see if a user is available for chat.

Readers and Authors fields


Reader and Authors fields allow you to control who can read and create documents created from a form.

126 Application Development with Domino Designer 7


Because these fields work with the overall Designer security model, they are described in the chapter
″Security in an Application.″

Creating fields to display lists of choices


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

″Allow values ″Allow


Field Type Usage not in this list″ multi–values″
Dialog list Users either press ENTER or click the Available Available
entry helper button to see all the
choices at once, press the space bar to
display choices one at a time, or type a
letter to display the first choice
beginning with that letter. Select
″Display entry helper button″ if you
want to display a button next to the
field that a user clicks to view all the
choices. Dialog lists are not available in
layout regions.

Checkbox Each choice is displayed with a box Not available Available


users click to select. Checkboxes have
border, column, and spacing options. To
create a wide checkbox panel, choose a
column number between 2 and 8.

Radio button Each choice is displayed with a button; Not available Not available
users can click only one. Radio buttons
have border, column, and spacing
properties. To create a wide button
panel, choose a column number
between 2 and 8.

Listbox Each choice is displayed with an Not available Available


expanded list box. Users click an entry
to select it. List boxes have border, size,
and placement options. To resize the list
box without dragging it, change the
Width and Height measurements. To
move the list box in a layout region
without dragging it, change the Left
and Top measurements.

Chapter 6. Designing fields 127


″Allow values ″Allow
Field Type Usage not in this list″ multi–values″
Combobox Each choice is displayed with a Available Not available
drop-down list box. Users click arrows
to view the entries. They can then click
the one they want. Combo boxes have
border, width, and placement options.
To resize the combo box without
dragging it, change the Width
measurements. To move the combo box
in the layout region without dragging
it, change the Left and Top
measurements.

Generating choices for lists


When you are defining a list field, choose one of these options on the Control tab of the Field Properties
box for generating the list.

Note that only the Dialog list type contains all of the following options. The Checkbox, Radio button,
Listbox and Combobox types contain only the first two of the following options.

List field option Description


Enter choices (one per line) Type a list of choices in the edit box. Select Sort to display the list in
alphanumeric order. Click the green check mark to save your entries.
Choices can contain letters, numbers, and all punctuation characters except
commas.
Use formula for choices Type a formula in the formula window to generate a list of choices. Click
the green check mark to save your entries.
Use Address dialog for choices This option displays the Names dialog box so users can select names from
a Personal Address Book or Domino Directory. Click ″Look up names as
each character is entered″ to help users fill in a name quickly. Notes looks
up a match for the typed letters in the open Address Book or directory.
Use Access Control 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.

Use View dialog for choices


Looking up values in a view lets you retrieve data from databases. This is convenient for displaying
choices that change, such as customer names, sales territories, and job titles.

View lookups provide the following benefits:


v Non-designers can maintain choices without having access to the rest of the database design.
v Designers can avoid hard-coding choices into fields. This makes verification and maintenance easier.
v Designers can hide the design of the database without affecting maintenance of choices.
v Designers or administrators can customize the application or conveniently translate lookup information
to other languages.
v Users can review choices and codes more conveniently from outside the form or application.

Note: Use lookups sparingly because they adversely affect the performance of the application.

128 Application Development with Domino Designer 7


To retrieve information from Domino or non-Domino databases you can use @DbColumn and
@DbLookup formulas instead of using a View dialog lookup.

For more information on @DbColumn and @DbLookup, see the Domino Designer Programming Guide.

Examples: Creating a field to display a list of choices


You want to make it easy for users to include a product number when they fill out a Purchase Request.
Create an editable Dialog List field named ProductNumber and use the ″Use View Dialog for choices″
property to generate choices.

You select the Inventory Database, the By Product Number view, and Column 1, where product numbers
are listed.

Creating a formula-generated list


A Travel Request form contains an editable Listbox field called Country that uses the following formula
to show only those countries relevant to the location selected by the user:
@If(Location="Europe";"France":"Germany":"Italy":"Spain";Location="Far East";"Japan":"Singapore":
"South Korea";Location="North America";"Canada":"Mexico":"United States";"")

Creating aliases for choices in a list


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

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

Converting aliases to full category names


If you are creating a view with a categorized column that refers to choice list fields, you need to be aware
that the view will use the alias name as the category rather than the value that users see in documents.

For example, a field named RequestType contains the following choices:


Hardware Request | HW
Software Request | SW
Service Request | SVC

In a categorized view, the categories display as:


HW
SW
SVC

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

Chapter 6. Designing fields 129


Example: Using aliases for choices in a list
You want Service Repair Requests to have a field for product groups. Create an editable dialog list field
called Product and on the Control tab, select ″Enter choices (one per line).″ Include aliases, so that if the
product groups change, any formula referencing the alias still works. Enter this list:

Microwaves | 1

Ovens | 2

Refrigerators | 3

Specialty Items | 4

Toasters | 5

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

Password fields
A Password field is a text field that maintains a user’s privacy by displaying each character a user enters
as an asterisk on the screen. The contents of the Password field are not secure, and the data is visible in
the Document Properties box from the Notes client. There are several ways to secure the contents of a
Password field. If you are using the Password field as a method for securing an application, the best way
to secure the contents of a Password field is not to save the contents after the entry is verified. This can
be done using a formula that clears the field once it’s been verified. You can use the input translation
event or a LotusScript QuerySave event.

Example: Using an input translation formula


This formula is an input translation formula for a Password field. When the user enters a password,
Domino looks up the user in the Domino Directory and gets the user’s HTTPPassword field. Then, it
compares the value that the user inputs into the field with the HTTPPassword field. If the values match,
it presents a prompt saying ″You passed.″ If the values do not match the prompt says ″You entered an
incorrect password.″
x:=@DbLookup("";"Server/Acme":"names.nsf";"($Users)";@Username;"HTTPPassword");
REM "This compares the value above to the value the user entered after running it through the @Password
hash function and prompts the user whether they typed in a valid password or not.";
@if(@isError(x);@Prompt([OK];"Error";"Error");@Password(Password) = x;@Prompt([OK];"You passed";
"You passed");@Prompt([ok];"Password failure";"You entered an incorrect password"));
REM "This deletes the password field.";
@Unavailable

Example: Using a QuerySave event


This script determines whether the Password field contains a password.If it does it gets the name of the
author of the document and puts the abbreviated form of the name into the PublicEncryptionKeys field.
This effectively encrypts the Password field with the author’s public key. This does not involve a lookup
to the Domino Directory to get the key. It is retrieved from the user’s ID file.
Dim doc As NotesDocument
Dim db As NotesDatabase
Dim session As New NotesSession

130 Application Development with Domino Designer 7


Set db = session.CurrentDatabase
Set uidoc=Source
Set doc=source.Document
If doc.GetItemValue("Password")(0) <> "" Then
Set PkName = New NotesName(doc.GetItemValue("Author")(0))
Call doc.ReplaceItemValue("PublicEncryptionKeys", PkName.Abbreviated )
End If

Example 2: Using a QuerySave event


This script determines whether one or more password fields contains a password. If one of the fields
does contain a password, the script gets the values from the Author field and the OtherEditors field
(which might contain a group) and expands the OtherEditors field so that it has names and puts the
abbreviated form of the name into the PublicEncryptionKeys field. This effectively encrypts the password
field with the public keys for all unique entries in the two fields. This does involve a lookup to the
Domino Directory to get the keys for each of the users listed, unless the only value is the name of the
current user. If there is more than one name to look up, then it finds the public keys from the Domino
Directory. If the only key to look up is the author’s, it is retrieved from the user’s ID file.
Dim s As New NotesSession
Dim db As NotesDatabase
Dim doc As NotesDocument
Set db = s.CurrentDatabase
Dim uidoc As notesuidocument
Set uidoc=source
Set doc = uidoc.document
If (doc.GetItemValue("Password1")(0) <> "") Or (doc.GetItemValue("Password2")(0) <> "") Then
Call doc.ReplaceItemValue("PublicEncryptionKeys",Evaluate(|@Name([Abbreviate];
@Unique(Author:OtherEditors))|,doc))
End If

Formula fields
Formula fields are used to populate a subscription list, which works in conjunction with the
Headlines.nsf database. The Headlines database is used as the home page of a Notes client. The
Headlines database includes a feature called subscriptions. Each database designer has the option
enabling a database for subscriptions. When a user subscribes to a database (by choosing Create -
Subscription), it triggers a server task that will notify the user whenever a document of interest is saved
in that particular database. The criteria that the server looks for is contained in a formula field on the
subscription form. Although users fill out the subscription form in the database they want to subscribe to,
the subscription documents are stored in users’ headlines databases (the default is headlines.nsf) on their
local client.

If you want to create a custom subscription form for your database you can start with the default
subscription form, named $Subscription, in the HEADLINES.NSF or HEADLINES.NTF database that is
included with Designer. First copy and paste the form into your database, then customize it. When you
customize a subscription form you must include the formula field. The formula field on the $Subscription
form is named $HLFormula and is on the second tab of the tabbed table on the right side of the form.
The $HLFormula field is a computed field. If you choose to keep the formula field computed, you write a
formula that resolves to a selection formula for a subscription list. A formula field must resolve to a
selection formula in order for the server to be able to retrieve the subscription criteria for the user.

Another option for the formula field is to choose Literalize fields on the Field Info tab of the Field
Property box. When you select the Literalize fields option, you are programming the formula field to

Chapter 6. Designing fields 131


accept the formula you put in without compiling it. If you literalize a formula, the field references must
be: text, text list, number, number list, date, date range, or date list. If the field referenced is of any other
field type, it will be left out as a field reference.

The following is an example of a formula for a formula field for which Literalize is selected as an option:
Select (Names = ExampleNames) & (Numbers = ExampleNumbers) & (Categories = ExampleCategories) &
(Dates = ExampleDates)

If the current document has these fields and values:

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

Then the formula field will literalize to:


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

If you choose the computed option, the formula you enter must resolve to another formula. This provides
the ability to optimize complicated formulas before they are saved. After the formula is evaluated, the
resulting formula is saved.

If the resulting formula is invalid, the field is saved with a value of type error. In some cases, the user
would never be able to exit out of the document. To differentiate between success and failure, you should
test in the QuerySave event to determine if the Formula field is indeed a formula. If it is not, then the
computation did not result in a valid formula.

For example, a computed formula field has the following formula:


tLitNames := "\"" + @Implode( ExampleNames; "\" : \"") + "\"";
tLitNumbers := @Implode( @Text(ExampleNumbers); " : ");
tLitCategories := "\"" + @Implode( ExampleCategories; "\" : \"") + "\"";
"Select (Names = " + tLitNames + ") & (Numbers = " + tLitNumbers + ") & (Categories = " +
tLitCategories + ")"

If the current document has these fields and values:

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

Then the formula will compile to:


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

Color fields
A color field lets you display a color picker on a form. When the user clicks the down arrow of a color
field, a color chart appears with two tabs. The user can choose a color using either tab.

132 Application Development with Domino Designer 7


v At the Notes/Web tab, the user can choose from a Lotus Notes color palette or a Web color palette.
Note that the Notes tab becomes the Web tab only if the user has enabled ″Use Web palette″ (File -
Preferences - User Preferences).
The RGB (Red, Green, Blue) value appears at the bottom of the palette for each color. If you are using
the Notes palette, the name of the color also appears.
v At the RGB tab, the user can either enter values from 0-255 for Red, Green, and Blue or can use the
RGB sliding arrows to choose a value from 0-255. The mixed color appears in the box to the right of
the RGB values. The user can also use the color matrix bars at the bottom of the pane to define a color.

Note that the user must be running in a color mode greater than 256 color to see the real color. If a user
enters an RGB not in the palette and the user is in 256 color mode, then the closest color in the palette
will be displayed for the RGB. The correct RGB will be stored and will appear correctly on systems with
greater than 256 colors.

The chosen color is stored in RGB hexadecimal format.

Time zone fields


A time zone field lets you display a drop-down list of all available time zones in the world, including the
local time zone. Each time zone listed includes a partial list of the cities or locations found in that time
zone.

Editable and computed fields


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

Writing field formulas


You enter field formulas in the Script area of the Programmer’s pane. First, choose the event for which
you are providing the formula from the Object tab of the Info List. For example, the default value event
provides an initial value for an editable field. If you include a Date field on a form, you might want to
enter a default value formula of @Today. This populates the field with today’s date.

Use the Reference tab in the Programmer’s pane to access the list of fields, @commands, and @functions.
You can use the Reference list as a shortcut for looking up @functions and @commands, and for pasting
them into the formula.

For information on writing formulas for fields, see the Domino Designer Programming Guide.

Computed field formulas


Computed fields are used to automatically enter data, such as the author’s name or the date, in a field.
You can have more than one computed field on a form. Computed fields require formulas to supply their
values. For example, you use a computed field to assign a creation date to a document. Computed fields
are normally recalculated when users create documents, choose View – Refresh Fields, press F9, or save
documents. Selecting the field property ″Compute after validation″ is useful when a field is dependent on
values in other fields and you want to be sure that the calculation occurs after those fields have been
validated.

When it’s important for users to see results as they proceed, you can force each field to be calculated as
it’s filled in by selecting the form property ″Automatically refresh fields.″ This is useful when fields at the
bottom of the form are dependent on field values at the top. Be aware that this property can slow down
document display time if the form has many computed fields.

Chapter 6. Designing fields 133


There are three types of computed fields:

Type of computed field Formula calculates


Computed A computed field formula calculates each time a user creates, saves, or refreshes
a document.
Computed when composed A computed-when-composed field formula calculates only once: when the user
first creates the document. Use this type of formula in a field to preserve
information about the origin of a document, such as the creation date or original
author, or to create a field whose original value never changes, such as a
document sequence number.
Computed for display A computed-for-display field formula recalculates each time a user opens or
saves a document. Use this type of formula in a field to display information that
is relevant only to the immediate session, such as the current time or the results
of calculations that you don’t need to save. The field value exists during the
current session only and is not stored. You cannot display the contents of a
computed–for–display field in a view.

To create a formula for the value of a computed field


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

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

Editable field formulas


You can write up to three formulas for each editable field:
v The default value formula provides an initial value that the user can change. Providing a default value
for an editable field ensures that the field gets filled in and often removes the need for users to enter
data such as their name or the date.
v The input translation formula modifies the contents of a field after a user fills it in -- for example, to
correct typing or standardize the format. Use an input translation formula to format information
entered by users -- for example, to make all entries uppercase. The result of the formula replaces what
the user entered. Input translation formulas are evaluated each time a document is saved, recalculated,
or refreshed.
v The input validation formula checks the contents of a field against predefined criteria, making sure the
entry meets certain requirements. For example, use an input validation formula to ensure that users fill
in a required field. Input validation formulas are evaluated each time a document is saved,
recalculated, or refreshed.
v The input enabled formula enables or disable the field for input. If Input Enabled evaluates to 0, data
cannot be added to the field. If it evaluates to anything else, data can be added to the field.

134 Application Development with Domino Designer 7


Input Enabled appears in the Object list of the Programmer’s Pane for all field types except rich text
and rich text lite.

To create a default value or input translation formula


1. Create an editable field.
2. Select Default Value or Input translation from the Object tab of the Info List.
3. Write one of the following in the Script area of the Programmer’s pane:
v A formula
v A field name
v A text string in quotation marks
4. Click the green check mark to verify and save the formula.

To enter a literal text string, enclose it in quotation marks (″ ″). Field names don’t 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.

An alternative to an input translation formula is to write a script for the Exiting event that verifies
information.

To create an input validation formula


1. Create an editable field.
2. Select the Input Validation event from the Objects tab of the Info List.
3. Write a formula in the Script area of the Programmer’s pane using @Failure and @Success.
4. Click the green check mark to save the formula.

@Failure prevents the user from saving the document until the user enters a value that meets the criteria.
As part of the formula, include text that clearly indicates what is wrong and how the user can correct it.

For information on writing formulas for fields, see the Domino Designer Programming Guide.

Selected field properties


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

Using Notes Style or Native OS Style


If you choose the field property ″Notes style″ for an editable field, such as Text, Authors, Readers,
Names, or Number, the field appears as a blank space marked off by brackets. The field expands
depending on what is entered into the field. At the Control tab of the Field Properties box, you can
uncheck ″Show field delimiters″ if you do not want brackets to appear at the beginning and end of the
field.

If you choose the field property ″Native OS style″ for an editable field, such as Text, Authors, Readers,
Names, or Number, the field appears on the document as an outlined box (whose height and width you
can set) instead of as blank space marked off by brackets. An editable Date/Time field displays as a
graphical date/time control. On the Web, native controls are ignored and fields display in their default
format. At the Control tab of the Field Properties box, you can set a border style (choosing no border,
single-line border, or a border that displays the field as inset) and can choose to display the field as
multiple lines.
Chapter 6. Designing fields 135
Property Choose one
Width v Fixed (Size) - lets you set a fixed width in inches.
v Fit to window (%) - fits the field to the window as the percentage you set.
v Fixed (Characters) - lets you set a fixed width in characters.
Height v Fixed - lets you set a fixed height in inches.
v Dynamic - increases the size of the entry box dynamically up to 3 lines. If an entry is
longer than 3 lines, scroll bars display automatically.
v Proportional - sets the heightproportionally to the width.

If you check ″Align control’s baseline with paragraph’s,″ the baseline of the characters in the field is
aligned with the baseline of the characters in the paragraph containing the field. This setting is especially
useful if you have no border around the field. The text in the borderless field will be on the same
baseline as the text in the paragraph containing the field.

Automatically refreshing field values


Sometimes users must see the results of all field calculations as they work on a document. To provide
continuously updating information, design a form that recalculates fields automatically whenever a field
value changes. Be aware this setting slows down a document’s display and data-entry time.

You can refresh field values in the following ways:


v Automatically, by setting a form property that refreshes all keyword fields as the user edits a
document.
v Automatically, by setting individual field properties to refresh based on the event you choose. For
example, you might set a keyword field to refresh automatically when a keyword changes.
v Manually, when a user manually refreshes a document.

For choice list fields enable the field property ″Refresh field on keyword change″ on the Control tab of
the Field Properties box, for better performance on large documents with many computed fields. This
field property refreshes all the fields on a form only after a user selects a value for a specific choice field
that has the property enabled. The option ″Refresh choice on document refresh″ refreshes the choice list
choices when a user refreshes the document by choosing View - Refresh. You can also write a LotusScript
field event to recalculate the document or update other fields when users move from a specific field.

To refresh field values automatically


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

Making a field active by default


The first editable field on a form is the active field by default. You can override this setting and change
which field is active when a user creates or edits a document.

Changing the default active field helps emphasize an editable field that isn’t located at the top of the
form, or directs users to a field that is the most frequently edited field on the form or to a required field
that you don’t want users to miss.

This option applies only to editable fields.


1. Create a field, or click an existing field. Then choose Design - Field Properties.
2. On the Field Info tab, select ″Give this field initial (default) focus.

136 Application Development with Domino Designer 7


Hiding fields
Use hidden fields to perform interim calculations or to store information you do not want users to see. In
the Designer templates, hidden fields appear at the bottom of forms, preceded by the heading ″Hidden
fields.″

Hiding fields is not a security feature. Users can see the value of hidden fields on the Fields tab of the
Document Properties box in the Notes client. To keep the data fields safe, encrypt, rather than hide, the
fields.

Hiding options
When you hide a field, you are actually hiding the paragraph on the form that contains the field. If there
is text, such as a field label or graphics, in that paragraph, Designer hides them with the field. You can
hide a field and any associated text or graphic all the time or only at certain times. For example,
information useful only when users create or edit documents can be hidden during reading, printing, and
copying; information that is used for display, such as a computed field that displays the result of an
author’s choice in an editable choice list field, can be hidden during editing.

The following are options for hiding fields:


v Hide paragraph from Notes 4.6 or later
Information is hidden when the application opens on a Notes 4.6 workstation.
v Hide paragraph from Web browsers
The information is hidden when the application opens on a Web browser.
v Mobile
The information is hidden for Mobile users.

If the paragraph is hidden when Then


Previewed for reading The hidden information isn’t visible when users read documents in the
document preview pane.
Previewed for editing The hidden information isn’t visible when users work on documents in
Edit mode in the document preview pane.
Opened for reading The hidden information isn’t visible when users open documents in Read
mode. A field that can’t be read can’t be printed either.
Opened for editing The hidden information isn’t visible when users work on documents in
Edit mode.
Printed The hidden information isn’t visible on printed documents.
Copied to the clipboard The hidden information isn’t visible when information is copied to and
pasted from the Clipboard. This setting doesn’t affect documents copied
at the view level.
Embedded The hidden information isn’t visible when the document is an embedded
document.
Hide paragraph if formula is true A formula determines the circumstances in which information is hidden.

To hide a field
If you have computed fields that users don’t need to see, or if you create two fields -- one for display
when reading and one for use when editing -- you can stipulate when to hide the fields.
1. Select the field you want to hide.
2. Choose Design - Field Properties.
3. On the Hide tab, do one of the following:

Chapter 6. Designing fields 137


v Select ″Hide paragraph when document is:″ and click all situations when users don’t need to see
the field information.
v Select ″Hide paragraph if formula is true″ and write a formula in the formula window on the
Properties box to describe the situations when users don’t need to see the fields.
For more information on using a formula to hide a paragraph, see the Domino Designer Programming
Guide.

Choosing ″Refresh fields when keywords change″ displays documents faster than the form property
″Automatically refresh fields.″ It is useful for showing or hiding parts of the form when you have
hide-when formulas that are dependent on values in the field.

Examples
To make documents more readable, you decide to modify the Marketing Ideas form to show only the
model name for the product that the author selects.

The Models field is a radio button field that displays these choices for refrigerator models:

Econo-Freeze

Icebox 2000

InstaFreeze

Premium

The Chiller

You hide the Models field when previewed and opened for reading.

You create a computed text field called SelectedModel and locate it under the Models field.
SelectedModel uses the value from the Models field. You hide the SelectedModel field when opened for
editing.

Now when users create a new document, all model names are shown. When users read a document, they
see only the model name chosen by the author.

Creating a field in a layout region


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

Layout regions are not supported in Web applications.

To create a field in a layout region


1. Open the form.
2. Click the layout region and choose Create - Field.

138 Application Development with Domino Designer 7


3. Choose Design - Field Properties and assign a name to the field.
4. Assign a field type and then select Editable or a computed option.

Note: You cannot use the following field types in a layout region: Color, Dialog List, Formula,
Password, Rich Text, Rich Text Lite, or Time Zone.
5. Drag the field horizontally or vertically to adjust its width and height.

To create a field label


1. Choose Create - Layout Region - Text.
2. Click the text area, choose Design - Object Properties, and type a field label in the Text box. Click the
check mark.
3. Drag the text area above or to the left of the field and drag it to the size you want.
4. Click the Font tab to change the text style for the label.

To resize a field
Placing a field in a layout region allows you to adjust the way field values appear or to limit the number
of characters users can enter in a field. To resize a field, drag the borders of the field.

Adding HTML attributes to a field


There are two places to attach HTML to a field. Use the Field Extra HTML tab on the Field Properties
box, or use the HTML Attributes field event to attach HTML formatting attributes to editable fields. By
adding HTML code to a text field you can, for example, lengthen that field when it is viewed through a
browser.

To add HTML attributes using the Field Properties box:


1. Double-click the field you want to format.
2. Select the Field Extra HTML tab on the Field Properties Box.
3. In the Other HTML tag field, enter the HTML code (without quotes) -- for example, to resize a text
field from its default size of 20):
SIZE=75 MAXLENGTH=100
The maxlength value defines the length of the text content a user can enter into the field. Keep the
maxlength value approximately 30 percent larger than the size value to enable a user to completely
fill a field with text.
4. Save the form.

To add HTML attributes using the field’s HTML Attributes event:


1. Click the field you want to format.
2. On the Objects tab of the Info List in the Programmer’s pane, select the HTML Attributes event for
the field.
3. Write the HTML code in quotes in the Script area -- for example, to define a rich text field’s
properties:
"ROWS=10 COLS=20"
4. Save the form.

Chapter 6. Designing fields 139


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

Creating fields that inherit values


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

For more information on Domino URL commands, see the appendix ″URL commands for Web
applications.″

To create a field that inherits values from another document


Create fields that inherit information from another document to save users from unnecessary typing or to
keep related documents consistent. Open the form.
1. Choose Design - Form Properties.
2. (Optional) To display the parent document to end users in the preview pane of the Notes client, click
the Defaults tab, select ″On Open: Show context pane″ and select Parent.
3. Select ″On Create: Formulas inherit values from selected document.″
4. Create the fields that should inherit values.
5. Write a default value or computed field formula for each field that uses the parent document field
name as the value. For example, to inherit the FullName field, use FullName as the inheriting field’s
formula.

Example: Inheriting address information


In a Customer Contacts application, a Letter form uses inheritance to copy information from a Company
Profile document. The Company Profile contains name and address fields and a hidden field called
FullName. The Letter form inherits the values of the name and address fields for the address block and
uses the FullName field for the salutation.

When Notes client users highlight a Company Profile document and choose Create – Letter, the Letter is
already filled in with the recipient’s name, address, and the correct salutation.

140 Application Development with Domino Designer 7


When Web users open the Company Profile document and click a button to create a Letter document, the
Letter is already filled in with the recipient’s name, address and the correct salutation.

To create a field that inherits an entire document


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

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

To Inherit information in a response hierarchy


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

Standard fields used in templates


The following fields are frequently used in the templates that ship with Designer. You may want to
follow the same standards in databases you design to maintain consistency and make it easier to share
information between forms.

Field name Field purpose


Body Editable rich-text field that stores most of the information in a document.
ComposedDate Hidden, computed-when-composed, date/time field that uses the formula @Created.
From Computed-when-composed, Authors field that uses the formula @UserName.
Subject Editable text field that contains a one–line document summary.

Chapter 6. Designing fields 141


Predefined fields with built-in functionality
Designer provides predefined fields which automatically add functionality that you would otherwise
have to program yourself. For example, to design a form with mailing options, you add predefined mail
fields such as SendTo and CopyTo to a form. Designer recognizes the fields and provides the interaction
with the mail router that routes and delivers the mailed document.

If you try to use a reserved name in a way that is different from its intended use or redefine the field,
Designer displays an error message.

Reserved names for embedded elements


Reserved field name Contains
$$ViewBody An embedded view.
$$ViewList An embedded folder pane.
$$NavigatorBody An embedded navigator.
$GroupScheduleRefreshMode A value for refreshing an embedded group scheduling
control.
$GroupScheduleShowLegend A value of 0 or 1. If the value is 0, the color legend does not
display. If the value is 1, the color legend does display. The
default is 1.

Reserved fields for use in billing applications


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

Reserved fields for general use


Reserved field name Use
Categories Categorizes documents.
$VersionOpt Controls version tracking for documents.
FolderOptions Puts new documents in folders.
SecretEncryptionKeys Encrypts documents with secret, rather than public, encryption keys.
HTML Passes HTML directly to the server.
$$HTMLHead Passes HTML information to be hosted within the <HEAD> tag for a
document. The passed information might be meta data (using a <META
...> tag) or JavaScript code (using a <SCRIPT ...> tag) or CSS information
(using a <STYLE ...> tag).
$$Return 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.

142 Application Development with Domino Designer 7


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

Reserved fields that control mailing options


To build mailing options into a form, create fields that have reserved names in Designer. When you create
a field with one of these reserved names, built-in programming takes care of the task for you. The fields
can be text or choice list fields that use predefined values.

For information on text fields, see the topic ″Text, rich text, and rich text lite fields″ in this chapter.

For information on choice list fields, see the topic ″Creating fields to display lists of choices″ in this
chapter.

For information on editable and computed fields, see the topic ″Editable and computed fields″ in this
chapter.

For information about mail-enabling forms, see the topic ″Features that support automatic mailing″ in the
chapter ″Creating a Workflow Application.″

Table of fields that control mailing options


Reserved Field name Values Comments
BlindCopyTo The name(s) of a person, group, or
mail-in database.
CopyTo The name(s) of a person, group, or
mail-in database.
DeliveryPriority L, N, H Values correspond to: Low, normal, or
high-priority.
DeliveryReport N, B, C, T Values correspond to: None, Only on failure,
Confirm delivery, Trace entire path
Encrypt 1, 0 Use 1 to encrypt mailed documents.
MailFormat B, E, M, T Enables cc:Mail users to view Notes documents
in a variety of predefined formats:

B = both text and encapsulated.

E = encapsulated in a Notes database, which is


attached to the cc:Mail memo.

M = mail. Body field of document is text and


pasted into cc:Mail memo.

T = text. Contents of the document are rendered


as text and pasted into the body of the cc:Mail
memo.
MailOptions 1, 0 Use 1 for automatic mailing.
ReturnReceipt 1, 0 Use 1 to send a receipt when document is
opened by the recipient.
SaveOptions 1, 0 Use 1 to save mailed documents. Use 0 so that
the document is not saved when mailed.
prevent the document from being saved.

Chapter 6. Designing fields 143


Reserved Field name Values Comments
SendTo The name(s) of a person, group, or Required for all forms that mail documents.
mail-in database.
Sign 1, 0 Use 1 to an add electronic signature to fields.
(Only applicable if a form also contains
sign-enabled fields.)

Tip: If you write a LotusScript program that uses the Send method of the NotesDocument class or a
formula that uses @MailSend, you can include many of the above mailing options in the script or
formula.

For more information on using LotusScript, see the Domino Designer Programming Guide.

Interactions with the Mail Send dialog box


The MailOptions field with a value of 1 overrides the user’s choices in the Mail Send dialog box if the
form is set to enable optional mailing. With a MailOptions field set to 1, users can click Yes to save the
document, No to close without saving, or Cancel to return to the document.

The Sign, Encrypt, and SaveOptions fields with values of 1 override the property ″On Close: Present mail
send dialog″ in the Form Properties box, but they do not actually change what is displayed to users in
the Mail Send dialog box.

Interactions with the Document Save dialog box


The values in SaveOptions, Sign, and Encrypt fields override the user’s settings in the Document Save
dialog box.

MailFormat
A computed MailFormat field can have one of the following values:

Value Description
Encapsulated (E) The document is encapsulated in a database, which is attached to the cc:Mail memo.
The cc:Mail recipient must have the Notes client installed on the workstation. This
preserves the document exactly as it looks in Notes. To read the document, the cc:Mail
user double–clicks the icon representing the attached database; this launches Notes and
opens the database. Use this format only if information will be lost if the document
were to be converted to Text or Memo format. The Encapsulated format creates larger
documents, so it uses more server disk space. To ensure that the document is displayed
correctly when a cc:Mail recipient starts Notes, assign the form property ″Store form in
document″ in the Form Properties box.
Text (Text) The contents of the document are rendered as text and pasted into the body of the
cc:Mail memo. The cc:Mail recipient can read the document without using Notes. Since
the document is rendered as text, you do not need to store the form in the document.
Both (B) The document is both rendered as text and encapsulated in a database. This ensures
that cc:Mail recipients can read the document even if they do not use Notes.
Mail (M) The Body field of the document is rendered as text and pasted into the cc:Mail memo.
Use this format only with documents that were created using a form that contains a
field named Body.

MailOptions
The MailOptions field with a value of 1 overrides the property ″On Close: Present mail send dialog″ in
the Form Properties box. With a MailOptions field set to 1, users can click Yes to save the document, No

144 Application Development with Domino Designer 7


to close without saving, or Cancel to return to the document. To add the mail signing and encryption
options, create editable keywords fields named Sign and Encrypt.

SendTo
The ″Allow multi-values″ and ″Allow values not in list″ are useful for SendTo fields.

Fields for version tracking


Adding a $VersionOpt field to a form allows users to create new versions of edited documents on a
document-by-document basis.

To create a computed $VersionOpt field


Use a computed text field if you want each document created from a form to have the same version
control option.
1. Create a field named $VersionOpt and define it as a computed text field.
Computed-for-display and computed-when-composed fields do not work in this situation.
2. Select Value on the Objects tab of the Info List in the Programmer’s pane.
3. In the Script area enter one of 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

To create a choice list $VersionOpt field


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

Chapter 6. Designing fields 145


Designing fields that prompt users to select folders
Adding a FolderOptions field to a form lets users select a folder for new documents without having to
choose Actions - Move to Folder after saving. You can define the field so that users are prompted to
choose a folder or so that a document is automatically saved to the current folder.
1. Create a field named FolderOptions and define it as a computed text field, computed number field, or
an editable choice list field.
Do not select ″Allow multi-values″ or ″Allow values not in the list.″
Computed-for-display and computed-when-composed fields do not work in this situation.
2. For a choice list field, on the Control tab of the Field Properties box, select ″Enter choices (one per
line)″ and write each entry, using a keyword and its equivalent synonym -- for example:
Choose folder from list | 1
Save in current folder | 2
3. For a computed field, select Value from the Objects tab of the Info List in the Programmer’s pane.
For an editable field, select Default value from the Objects tab of the Info List in the Programmer’s
pane.
4. Write a formula in the Script area of the Programmer’s pane.
The FolderOptions field must contain the value or default value 1 or 2.
″1″ (Prompts user to choose folder)
This value prompts the user with the ″Move to Folder″ dialog box. Selecting a folder and clicking
Add puts the new document in a folder. Selecting Cancel saves the document without putting it in a
folder.
″2″ (Save to current folder)
If the user is creating the document from an open folder, this value saves and adds the document to
that folder. If the user is not creating the document from a folder, the document is saved but not
added to a folder.

146 Application Development with Domino Designer 7


Chapter 7. Designing framesets
A frameset is a collection of frames and can add structure to your Web site or Notes database. A frame is
one section, or pane, of the larger frameset window and is independently scrollable.

A frame can contain a form, folder, page, document, view, navigator, or frameset. The frame can also
contain a Web page and be associated with a specific URL. Framesets let you create links and
relationships between frames. For example, you can leave one page displayed as users scroll or link to
other pages or databases.

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

Note: Framesets created with Domino Designer Release 5 and later do not work with releases of Lotus
Notes before Release 5. A database opened by a previous version of Notes will be launched using
″restored as last viewed by user.″

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

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

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

Using the View menu with framesets


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

Providing content for a frame


When you first create a frameset, the text ″No content″ appears in each frame. To provide content for a
frame in a frameset, you can do the following:
1. Select a frame in the frameset.
2. Choose Frame - Frame properties. The Frame Properties box appears.
3. On the Basics tab, provide a name for the frame.

148 Application Development with Domino Designer 7


Make sure that each frame has a unique name. Using the same name for frames in different framesets
is not recommended. For example, if you have a frame named Banner in more than one frameset, you
may get unexpected results when you set it as a target frame.
Note that you should not use HTML predefined target names to name a frame ( _self, _top, _parent,
and _blank).
4. At the Type field of the Basics tab, choose one of the following ways to provide content for the frame:
v Link
Link requires that you paste in a link that you’ve already copied to the Clipboard. Click the Paste
icon to paste in the link. There are three kinds of links you can paste in from the Clipboard: View,
Document, or Anchor. (Database links are not supported in framesets.)
For more information on links, see the topic ″Creating Links″ in the chapter ″Designing Pages.″
v Named Element
A named element is a design element that you have already created and named. A named element
can be a page, form, frameset, view, folder, or navigator.
Enter a value (for example, if you already created a page named PAGE1, enter it into the Value
field). Alternately, you can click one of the following icons:
v Formula icon (@) to use a formula that evaluates to a name.
v Paste icon to paste in a name which you previously copied to the Clipboard.
v Folder icon to open the Locate Object dialog box and select a design element from a list of
elements.
If you choose Named Element - View or Folder, several options appear:
v Show action bar displays the View action bar when the view or folder is loaded into the frame.
v Show header displays the column headings.
v Selection tracks mouse movement - as you move the mouse over the view, the view selects the
document the mouse is pointing to.
v Basic simple appearance - enables several miscellaneous options, including such options as showing
strike-through text when an item is marked for deletion, not allowing the scroll bar to be hidden,
not extending selection in the selection margin when the mouse moves, using a simple grid for
calendar views, and defaulting to a 1-day format for calendar views.
v If you want a view or folder on the Web, consider first embedding the view or folder on a page or
form. If you choose to make the embedded view an embedded view applet, you preserve much of
the HTML view functionality and provide features such as resizeable columns, multiple document
selection, and scrolling.
v URL
To put a Web page into a frame, choose URL and enter the full URL specification (for example,
http://www.lotus.com). You can also paste in a URL or use a formula that evaluates to a URL. You
receive an error in the frame if the URL you specify is not accessible. Note that all content rendered
in framesets in Designer uses the native Notes Web browser even if your current browser selection
is something else.
When you click a link in a Web page (in the Notes client or in a Web browser), the link may open
within the same Web page or in a new window, depending on the setting for that Web page.
5. (Optional) Enter the target frame for links activated within the current frame.

Setting the style for frames


You can set properties such as scroll bars, size of frames, and border properties in the Frame Properties
box.

Note: The Web browser you use may not fully support all the properties you can set in the Frame
Properties box.

Chapter 7. Designing framesets 149


To set the style for each frame:
1. Choose Frame - Frame Properties.
2. Specify the following properties for each frame.
For information on the Basics tab of the Frame Properties box, see the previous topic ″Providing
content for a frame.″

Tab Property Description


Frame Size tab Width and Height Choose relative, percent, or pixel to specify the frame width and height:
v Relative -- sizes the frame relative to the other frames in the frameset. For
example, a frame with no frames above or below it is automatically set to
relative and is the height of the frameset.
v Percent -- sizes the frame as a percentage of the frameset. A frame set to
50 Percent width is half the width of the frameset.
v Pixel -- sizes the frame exactly in pixels.
Note: If you change the width and height properties for one frame, the
width and height of adjacent frames will change; however, the properties of
adjacent frames are not automatically adjusted. Adjacent frame properties are
adjusted if you drag the borders.
Scrolling Choosing On forces a scroll bar for the frame; choosing Off causes no scroll
bar to appear. If you choose Auto, the scroll bar appears if it is needed. The
default is Auto.
Allow Resizing Allow Resizing. If you choose Yes, you allow users in the Notes client or
Web browser to change the height and width of frames by dragging their
borders. If you choose No, users cannot drag borders to re-size the frame.
Set Initial Focus Checking this box causes the focus to be on this frame when the frameset is
launched in the Notes client. This feature works only with Lotus Domino
Designer 6 and later and is ignored by previous versions. If this property is
enabled for more than one frame in a frameset, the first frame found is
enabled. If this property in enabled on a frame that either has no content or
has content which cannot be found, there is no frame focus.
Frame Border Border Style v 3-D border -- allows three-dimensional borders between the current frame
tab (Applies to this and its adjacent frames.
frame)
v Apply to all frames -- adds three-dimensional borders between all frames
in the frameset.
Border style v Border width (in pixels). The default is 7 pixels. Checking Default means
(Applies to all that the frame displays according to the user’s browser settings. Each
borders in browser renders design elements differently, so be sure to preview your
frameset) work in each browser if you are choosing this setting.
v Border color -- choose a color from the drop-down color chart. Click on
the system (monitor) icon at the top of the color chart to get the default
color. Click on the wheel icon at the top of the color chart to create a
custom color.

150 Application Development with Domino Designer 7


Tab Property Description
Border Caption v Caption Formula -- enter a formula that translates to a caption that
(Notes Client appears in the border.
Only)
v Show -- choose None, Caption only, Arrows only, or Both. None shows the
default border with no caption or arrows.″ Caption only″ displays a
caption in the border. ″Arrows only″ displays an arrow in the border. This
arrow lets you open and close the frame. Both displays both a caption and
an arrow in the border.
v Align - for a caption, choose to align so that the caption appears inside the
top or bottom border of the frame. For an arrow, choose to align so the
arrow appears at the top, bottom, left, or right border of the frame. For
both a caption and an arrow, you can align top or bottom. Note that the
border appears only where the caption or arrows appear. For example, if
you choose ″Top,″ then the border displays on the top only.
v Justify - choose to justify the caption or arrows so they appear to the left,
right, or center of the border.
v Open - choose a size in pixels or as a percent of the frame. This size is the
default size that the frame opens to when the user clicks on the border of
a closed frame.
v You can also specify text characteristics for the caption and arrows, such
as font, size, style, and color. In addition, you can specify a background
color for the border.
Advanced tab Frame Spacing The default is minimal space between frames. You specify spacing between
frames in pixels. Checking Default means that the frame displays according
to the user’s browser settings. Each browser renders design elements
differently, so be sure to preview your work in each browser if you are
choosing this setting.
Margin Height and The default is minimal space between the frame border and the frame
Width content. You specify height and width in pixels. Checking Default means
that the frame displays according to the user’s browser settings. Each
browser renders design elements differently, so be sure to preview your
work in each browser if you are choosing this setting. This property is not
supported in the Notes client.

Specifying a target frame


In addition to adding content to a frame, you can target a specific frame of a frameset so that data and
links open in the target frame. You specify a target frame in the Frame Properties box or in the Properties
boxes of many other elements (such as the properties boxes for pages, forms, outline entries, embedded
outlines, group scheduler, and hotspot resources).

It is possible to set multiple target frames that appear to conflict with each other. For example, you can
set a target frame on an outline entry, an embedded outline that contains that outline entry, the page that
contains that embedded outline, or on a frame that contains the page. Which target frame takes
precedence?

The general rule is that the most specific element takes precedence. In this case, it is the outline entry
which takes precedence. If you have not specified a target frame in the outline entry, then the target
frame set in the embedded outline takes precedence. If you have not specified a target frame in the
embedded outline, then the target frame set in the page containing the embedded outline takes
precedence. And if you have not specified a target frame in the page, then the target frame set in the
frame takes precedence.

Chapter 7. Designing framesets 151


If you have not specified a target frame anywhere in this hierarchy, the link opens in the frame that
contains the link. If you specify a target frame that does not exist, the link opens in a new, top-level
window.

Note that an embedded view and a view have the same level of precedence. Note also that if a frame
contains a page with an embedded view applet, then clicking a document in the embedded view applet
actually opens a new window which overwrites the original window.

For more information on specifying a target frame for an individual link or element, see the online help
for that element’s properties box.

Note: Remember to specify a name in the Frame Properties box for any frame that is going to be a target
frame.

Launching a database into a frameset


You can have a frameset display automatically when you open a Notes database:
1. Create the frameset you want to display when the database first opens.
2. In the Database Properties box, click the Launch tab.
3. In the On Database Open field, select Open Designated Frameset.
4. In the Name field, select the frameset you want to open.

When the database is opened, the specified frameset launches. If a view link, document link, or
@command is used to open a database, the frameset may not open.

Launching a page or form into a frameset


You can specify that either a page or a form and the documents created with that form open
automatically in a specific frame of a frameset.
1. Open the page or form you want to open in a frame.
2. Choose Design - <design element> properties to open the properties box for the page or form.
3. Click the Launch tab.
4. In the Frameset field, select the frameset in which you wish to launch the page or form and the
documents that are created with that form.
5. In the Frame field, select the frame in which you wish to display the page or form and documents.

Note that you can select only framesets that are located in the same database as the form on which you
are working. Make sure that you have already saved the frameset and given the frame a name in the
Frame Properties box.

Launching a view or folder into a frameset


You can specify that a view or folder open automatically in a specific frame of a frameset. Note that this
autolaunch feature for views and folders works only on the Web.
1. Open the view or folder that you want to open in a frame.
2. Open the View or Folder properties box for that view or folder.
3. Click the Launch tab.
4. In the Frameset field, select the frameset in which you wish to launch the view or folder.
5. In the Frame field, select the frame in which you wish to display the view or folder.

152 Application Development with Domino Designer 7


Note that you can select only framesets that are located in the same database as the view or folder on
which you are working. Make sure that you have already saved the frameset and given the frame a name
in the Frame Properties box.

Chapter 7. Designing framesets 153


154 Application Development with Domino Designer 7
Chapter 8. Designing views
A view is a sorted or categorized list of documents. Views are the entry points to the data stored in a
database. Every database must have at least one view, although most databases have more than one view.

Here are the general steps in planning your view.


1. Before you create the view, think about:
v Whether the view style will be an outline view or a calendar view.
v The type of view you want (shared, private, and so on).
v Whether the view will be displayed on the Web. If so you may want to consider creating an
embedded view on a form, subform, page, or document or consider creating a view applet or an
embedded view applet.
v The categories in the view.
2. Create the view by clicking ″New View″ in Designer.
3. Name the view.
4. Add columns to the view.
5. Set up the documents to display in the view by writing the view’s document selection formula.
6. Set up what will display in each column by programming the column value.
7. Set up the sorting order for the columns.
8. Set the style for the view, row, and columns.
9. Save and close the view.

Folders
Folders are containers used to store related documents or groupings of documents. Folders have the same
elements as views and are designed much the same way. For more information on designing folders, see
Notes Client Help.

Standard outline views


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

Here is the same view from a review database as shown through Netscape Navigator and through Notes.

155
To open a document in a standard view, Notes users double-click a row; Web users click a document link
in one of the columns.

A standard view on the Web maintains the column and row format of standard Notes views (unless you
use HTML formatting to customize a view), except that on the Web, a navigation bar on the top or
bottom of the screen contains buttons that users click to expand, collapse, and scroll the view.

156 Application Development with Domino Designer 7


On the Web, each time a 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 view in Notes does not apply to a view on the Web.

Displaying a view on the Web


By default, views are not enabled for display on the Web. For example, the ″For Web Access″ properties
of the Advanced tab of the View Properties box are not enabled. If you want to create a view for the
Web, consider creating a view applet or embedded view applet, as these options give you greater control
over the view display.

For more information on designing views for Web applications, see ″Displaying views in Web
applications″ later in this chapter.

Limits for views


A view can display no more than 32 levels of responses and/or subcategories. For example, if you have 6
levels of subcategories, you can display 25 levels of responses to a main document. If there are more
levels of responses than can be displayed, convert your view to a non-hierarchical, flat view, which
displays all documents on a single level (by deselecting ″Show response documents in a hierarchy″ in the
View Properties box).

The combined number of sub-level forms, views, and agents that cascade from the top level cannot
exceed 200; otherwise, the top-level menus do not display properly. This limit does not apply to the
number of forms, views, and macros stored at the top level of each menu.

Domino allows up to 200 cascading view and folder names to be displayed on the View menu.

Calendar views
A calendar view groups and displays documents in a calendar format. Such views are useful for
organizing documents that keep track of schedules, meetings, and appointments.

When you create a calendar view, you can give users the option to display the calendar in a variety of
formats, such as Two-Day, Work-Week, Week, Two-Week, or Month. Calendar views also let users:
v Navigate among days, months, and years.

Chapter 8. Designing views 157


v Print calendar entries for a selected range of days.

Web users can see all calendar entries. Domino converts calendar views to HTML tables. Therefore,
Domino restrictions for tables apply to calendar views. Web users cannot create new appointments or
scroll through entries within a single day.

Shared and private views


There are two types of views: shared (available to many users) and private (available to one person). You
designate the view type when you create the view and cannot change it later. A shared view can become
a private view on first use, but a private view cannot become a shared view without recreating it as such.

Shared views
Shared views are available to any user with at least Reader access to the database. Most views that you
design for databases are shared views. Users with Designer or Manager access can create shared views,
as can Editors for whom the manager has selected ″Create personal folders/views″ in the access control
list.

In addition to a basic shared view, you can create the following specific types of shared views:
v Shared, contains documents not in any folders
v Shared, contains deleted documents (used in conjunction with ″Allow soft deletions″ in the Advanced
tab of the Database Properties box)
v Shared, private on first use
v Shared, desktop private on first use (saves private views in users’ desktop.dsk files rather than in the
database)

Shared, contains documents not in any folders


A ″Shared, contains documents not in any folders″ view is useful if users typically file most documents in
folders. With this view, users can easily find the documents that are not in folders.

Shared, contains deleted documents


A ″Shared, contains deleted documents″ view allows users to view a list of documents deleted from the
database. Users can recover deleted documents by dragging them out of the trash to a folder. This view

158 Application Development with Domino Designer 7


assumes that the database manager has already selected ″Allow soft deletions″ at the Advanced tab of the
Database Properties box. The ″Allow soft deletions″ property keeps deleted documents in the database
for a set number of hours. The hours are set by the database manager in the Advanced tab of the
Database Properties box. After that time, the document is permanently deleted from the database.

Shared, private-on-first-use views


A ″Shared, private-on-first-use″ view begins as a shared view and becomes a private view as soon as a
user accesses and saves the view. These views give you a convenient way to distribute personal views to
multiple users. You usually create this type of view by using @UserName to customize the display for
each user.

Note that this is the only way to make a view work with @username, because the view selection is only
parsed when the view is generated. Thus, if Tom opened a shared view that keyed to @username, all of
Tom’s documents would display. But, if the view is still open when Jay accesses it, Jay sees all of Tom’s
documents, and does not see his own. So, to avoid this conflict, designate the view as ″Shared, private on
first use″ when using @username in the selection formula.

After a user saves a shared-to-private view, the user’s copy of the view no longer inherits design changes.
For example, if you add a column to the view, anyone using a private version of the view won’t see the
new column. To obtain design changes, users must delete their private versions of the view and open the
shared-to-private view again.

Shared-to-private views are not a security measure, as they do not protect data. If you create a
shared-to-private view that omits certain documents, a user can still create a private view that includes
them.

Shared-to-private views are stored in the database as long as they are shared. After the first use, Domino
uses the ″Create personal folders/views″ option to determine where to store the view.

Shared, desktop private-on-first-use views


If you want the shared-to-private view to be stored in a user’s desktop.dsk file rather than in the
database, choose ″Shared, desktop private on first use″ as the View Type when you create the view.

Private views
Users can create private views to organize documents in personalized ways by choosing Create - View.

If a user has rights to create private folders/views in the database access control list, private views are
stored in the Notes database. If the user does not have the access control list right to create private
folders/views, the user can only create and save private views in the user’s personal workspace file
(desktop.dsk).

Private views are not supported on the Web.

Creating a standard outline view


To design a view, you must have Designer access in the access control list of the database.

For information on database access, see the chapter ″Restricting Access to and Securing Parts of an
Application.″
1. Open a database in Designer.
2. Click Views in the Design pane.
3. Click the New View button above the Work pane. The Create View dialog box appears.
4. Enter a name for the view in the View name field.

Chapter 8. Designing views 159


5. Choose a View type in the View type field.
6. Select a location in the ″Select a location for the new view″ field.
If you want the view to appear at the top level in the list of views, do not select anything in this
field. Otherwise, click the name of the view under which you want the new view to appear.
7. Click ″Copy style from,″ then do the following:
v Click Blank if you do not want to copy another view’s style.
v Click the view whose style you want to copy. If the style uses selection by formula, the view’s
selection criteria appears in the ″Selection criteria″ field.
8. (Optional) When ″Select by formula″ is checked, you can use the Fields and Functions button and
Formula window button to further refine the new view’s selection criteria.
9. Click ″Save and Customize″ to open the View pane. Or, click OK to create the new view, then
double-click the new view in the Views list to open it.
The Column Properties box opens automatically with the first column of the view selected.
10. In the Column Info tab, enter a name for the column in the Title field. You can also specify other
properties of the column in this tab.
11. Click the Column Title tab to determine the font, size, color, and alignment of the column title. Click
the Font tab to do the same for values that display in the column.
12. Add other columns by choosing either:
v Create - Insert New Column to create a column to the left of the highlighted column.
v Create - Append New Column to add the column to the right of all existing columns.
13. Click each column in the Work pane. In the Programmer’s pane, add programming to determine the
column value. For example, a column can list the creation date or the size of each document.
14. Click the current view in the Objects list and expand it. Select ″View Selection″ and add
programming for the view’s document selection.
15. Choose Design - View Properties and click the Style tab to style the view.
16. Close and save the view.

Copying and deleting views

To copy a view
1. Click Views in the Design pane.
2. Select the view you want to copy, either in the design pane or in the work pane.
3. Choose Edit - Copy.
4. Choose Edit - Paste.
A copy of the selected view appears in the list of views. Until you rename it, the copied view is
named ″Copy of <selected view name>″. Future copies of the same view will be designated ″Another
copy of <selected view name>″.

To delete a view
1. Click Views in the Design pane.
2. Select the view you want to delete, either in the Design pane or in the Work pane.
3. Press the DEL key or choose Edit - Delete.

Creating a default design for new views


To save design time, designate a view as the standard for newly created views or folders in the database.

160 Application Development with Domino Designer 7


1. In Designer, open up the view or folder you want to use as a standard. You must use a shared view
or folder, not a private one.
2. Choose Design - View Properties.
3. Click the Options tab.
4. Select ″Default design for new folders and views.″

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

Note that Web users cannot drag documents into folders.

For more information on folders, see Lotus Notes Help.

Naming a view or folder


The name you choose for a view or folder is visible to Notes users in the View menu (unless the view is
hidden) and in the folders pane. The view name is visible to Web users in the Views list.

Naming tips
Keep these things in mind when naming views:
v The name is case-sensitive and can be any combination of characters, including letters, numbers,
spaces, and punctuation.
v The full name, including all aliases, can have up to 64 characters.
v Views appear in alphabetical order in the View menu in Notes and in the View lists on the Web. To
force names to appear in a different order, number or letter them. For example:
1. Zebra
2. Antelope

Note: Using an outline to organize views gives you greater control over the order in which views
display.
v If you start a name with a hyphen (-), the name appears before both numbers and letters.
v 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.
v Use consistent names across databases to make it easier for users to recognize views.

Aliases
An alias is another name, or synonym, for a particular view or folder. Use an alias to change or translate
the view name without causing lookup formulas that reference the view to stop working if the view
name is changed. Aliases follow the same naming rules as view names.

Note: If you are designing a multilingual database, limit yourself to one alias per view.

Enter an alias in the Alias field of the Info tab of the View or Folder Properties box. You can append
more than one alias by entering the vertical bar symbol (|) followed by the alias. Make sure you keep the
original alias as the rightmost name.
Main View | Top View | View1

Chapter 8. Designing views 161


Hidden views
When you surround a name with parentheses -- for example, (All) -- the view does not appear to Notes
users in the Notes View menu or to Web users or Notes users in the list of folders and views.

CAUTION:
Users can see hidden views by holding CTRL+SHIFT while selecting View/GoTo. Hiding a view is
not a security measure, but simply a design option.

For other ways to hide views, see Hiding a view later in this chapter.

Shortcut keys
Windows users can type shortcut letters to select a view or folder. The default shortcut, an underlined
letter in a view name, is the first letter in the name that has not already been used by a preceding name
on the menu. But if views or folders begin with the same letter, the default shortcut is the first letter that
has not already been used by a preceding name. If views or folders begin with the same letter, the
shortcut letters may be difficult to see and remember. For example, the shortcut letters (underlined) for
these views are
By Author
By Date

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

If you can’t change the names, you can specify a shortcut by typing an underscore before a letter to make
that letter the shortcut. For the By Date view, you can make the letter D the shortcut in this way:
By _Date

Cascading views
Creating cascading views lets you arrange lists of views in a hierarchy; that way, a group of related menu
items are organized under one item. A user clicks on the higher-level name to display the cascaded list.
You probably want to cascade views when you have long lists of views or when you have related views
that should be grouped together.

To create a cascading view, enter the name you want to appear on the Create menu followed by a
backslash (\), and then add the view name. For example, the Personal Address Book template has two
views related to servers:
Server\Certificates
Server\Connections

Customizing the style of the inbox folder


The administrator of the Lotus Notes mail database has the ability to customize the style of the mail
inbox. Administrators may choose from a selection of styles provided by Lotus, or use a previously
created style of their own.

The customization is made to the mail template, and will apply to all users of that mail database.

Using a previously created style


To use a previously customized inbox style from an older mail template, you will first need to copy the
inbox style folder design element from the old template to the new template.

162 Application Development with Domino Designer 7


1. Open the old mail template database in Designer.
2. Navigate to Folders.
3. Select the inbox style you want to use.
4. Select Edit - Copy.
5. Open the new mail template database in Designer.
6. Navigate to Folders.
7. Select Edit - Paste.
8. Edit the properties of the inbox style and change the name to ($Inbox-xxx), where xxx is a unique
identifier.

Selecting an inbox style


Selecting a new style will replace the existing ($Inbox) design element.

Note: Make a backup copy of the mail template before selecting a new inbox style.
1. Open the mail template database in Designer.
2. Navigate to Shared Code - Agents.
3. Select (Pick Inbox Style).
4. Select Agent - Run.
5. In the Pick Inbox Style dialog box, select the new style you wish to use. Click OK.
6. When asked if you want to continue, click Yes.
7. When prompted ″Inbox style update has completed″ click OK.
8. The Agent Log dialog box displays the run statistics of the agent. Click Done.
9. The new inbox style will not be available until after the database has been closed and reopened.

CAUTION:
The Notes ID that runs the (Pick Inbox Style) agent becomes the effective signer of the new ($Inbox)
design element.

Selecting 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 formula for new views combines the SELECT statement and the @All formula into
SELECT @All, which means ″include all database documents in this view.″ To narrow down the kinds of
documents the view displays, add a program that displays only particular documents. For example, in a
task-tracking database, the Work in Progress view could display only those documents whose Status field
does not contain ″Complete.″ In a brainstorming database, the Design Ideas view could display all
documents categorized as ″Design Suggestion.″ Here is a selection formula that displays only documents
containing new features and displays them in a What’s New view:

SELECT @IsMember(″01 What’s new?″; View)

Choosing the type of view selection


With a view you program the document selection in the Programmer’s pane. Choose ″View Selection″ in
the Objects box, select the type of programming you want to add, and build the program in the View
Selection pane.

Chapter 8. Designing views 163


Simple Search
Easy allows you to create a conditional document selection without knowing a programming language.
In the InfoList of the Programmer’s pane, click the Run list box and select Simple Search. Then click
″Add Condition″ for each selection you want to include. To delete a condition, click it and choose Edit -
Delete.

Formula
Formula allows you to create a program for selecting documents using the @function formula language.
In the Programmer’s pane, click Formula and write the formula in the Script area.

Examples: Programming documents to display in a view


The following examples describe various scenarios for selecting documents to display in a view.

Selecting documents by form name and field value


If a database contains an Action Item form with a Status field, a view in the database can select all
documents created with the form whose Status field has the value ″Open.″ The document 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 an Action Item form, 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 notcreated 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"

Selecting conflict documents


When two or more users make changes to the same document in different replicas of a database, conflicts
occur when replication updates the databases. A database displays conflict documents as responses to the
original document. In order to resolve conflicts, you may want to design a view that displays only the
conflict documents.

To display conflict documents in a view, make sure the options ″Display responses in a hierarchy″ is not
checked on the Options tab of the View properties box. Enter the following as the view selection formula:
SELECT @IsAvailable($Conflict)

Table of document selection conditions


Document selection conditions let you identify a particular set of documents. You can combine multiple
conditions to narrow down the selection. Click Add Condition to see the full list.

For more information about these conditions, see the section ″Descriptions of document selection
conditions″ that follows.

164 Application Development with Domino Designer 7


Condition Selection 1 Selection 2
By Author is any of <author name> or choose from Domino Directory

is not any of
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>
Fill out example form <example form name> lets you fill out a form with field values to search for
In folder <folder name>

Chapter 8. Designing views 165


Condition Selection 1 Selection 2
Multiple words any of the terms below search terms you specify

all of the terms below

Description of document selection conditions


Simple search conditions
The Simple Search condition determines whether a field contains one value. Because the Easy condition
reads any separators you enter as text, it can’t look for all the values in a multi-value field.

The Simple Search condition also can’t 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.

If you select By Authors, enter the name or names of the authors of the documents you want displayed,
separated by commas. If you know a user’s hierarchical name (such as Mary Sen/Development/Acme),
enter it. If you are not sure of how a name is spelled, use the Domino Directory to browse for person
names, but do not select any group names.

For more information, see ″Addressing a message by choosing names from an Address Book″ in Notes
Client Help.

Selecting documents by date


The ″Date created″ condition selects documents based on the ″Created date″ in the Document Properties
box.

The ″Date modified″ condition selects documents based on the ″Modified date″ in the Document
Properties box.

Selecting documents by field value


If the field is of type Text, Designer looks for the exact text string you enter. You can’t 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 isn’t 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
The ″By Form″ condition works only with forms that are part of the database design, not with forms
stored in documents.

CAUTION:
If you add an alias to a form that is referred to in an existing view or folder selection formula, the
formula will not display documents created or edited after the alias is assigned. You can fix this by
modifying the selection formula to include the alias, for example, changing the selection formula
from:
Form = "MyFormName"

to:
Form = "MyFormName" | Form = "MyFormAlias"

166 Application Development with Domino Designer 7


If you are using the Simple Search feature to select the form you can resolve the problem in this way:
1. Open the view in Designer.
2. Inspect the View Selection formula in the Programmer’s pane.
3. Click the Add Condition button to reselect the form name to include the new alias.
4. Save the view to update the selection formula.

Tip: It is good design practice to assign an alias to a form at the time of creation to avoid this problem.

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 the following:
| @IsResponseDoc

Creating columns in a view


Columns display one type of information about the documents listed -- such as the document subject,
author, or creation date. One column in a view is usually the organizing element -- for example, in a
chronological view, the organizing column displays document creation dates.

To add a column to a view in Designer, choose Create - Insert New Column or Create - Append New
Column.

A view can have a single column or as many columns as you can fit in 22.75 inches (the allotted width of
a view).

To copy a column, open the view in Designer, click the column, copy it to the clipboard, select the
column to the right of where you want the column to appear, and choose Edit - Paste. To select multiple
contiguous columns, select the leftmost column you want to copy, hold down the Shift key, and select the
rightmost column you want to copy. You can now copy or delete the columns as a group.

To delete a column, open the view in Designer, click the column, and choose Edit - Delete.

Creating a shared column


Shared columns allow the creation of a common column for insertion in multiple views in the same
database, eliminating the need to create the same column multiple times and creating a single point for
propagating changes to all views using the same column. A shared column has its own design element
but once inserted into a view is part of the view. A view containing a shared column is backwards
compatible for access from Notes and the Web.

To create a new shared column, select Columns under Shared Code. Click New Shared Column or choose
Create - Design - Shared Column. You can also copy and paste an existing Shared Column design
element.

To create a new shared column based on the design of an existing column in a view, open the view, select
the column, and choose Create - Copy As Shared Column. This action creates a new shared column and
leaves the existing view column as is.

The Shared Column design element has the same appearance and column properties as an unshared
column in a view.

In addition, the Shared Column design element has properties specific to shared columns. The Shared
Column properties box specifies the name of the shared column (required), an alias (optional), and a
comment (optional).

Chapter 8. Designing views 167


To use a shared column in a view, open the view and choose Create - Insert Shared Column or Create -
Append Shared Column. Select the shared column from the displayed list. Check the Use Formula Only
box if you want to override the shared column display properties, such as font and column alignment, in
the view. Leave the box unchecked to lock the display properties. The column programmatic name can
always be modified even if the Use Formula Only box is not checked, but you should change this name
only if it duplicates the programmatic name of another column in the view. You cannot modify the
column value (formula).

To see the names of the views using a shared column, select the shared column in Columns under Shared
Code and click Who is using this Shared Column.

To edit a shared column, double-click the Shared Column design element in Columns under Shared
Code. You can also edit a shared column by selecting it in a view and choosing Design - Edit Shared
Column.

When an existing shared column is edited and saved, all views containing the column are updated. These
views are resaved with the current user ID. Where Use Formula Only is checked, only the formula is
updated.

To delete a shared column, select the Shared Column design element. Press Delete or choose Edit -
Delete. When a shared column is deleted, the shared column is changed to an unshared column in all
views containing the column.

Shared columns may be used in DB2 Query views.

Shared columns, like shared fields, are not multilingual elements.

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, don’t include titles for every column.

Omitting a title
If you leave the title blank, the column doesn’t have any identifying text. Omit a title if the column is:
v A responses-only column that indents response documents
v A categorizing column for grouping related documents
v Hidden (and designers don’t need any identifying text when the view is Designer)
v Not relevant to users
v A column for displaying icons

Note: If users will be customizing the view, you can assign a column title, make the column editable, and
click the option ″Do not display title in column header″ on the Column Styles properties box. This will
suppress the display of the title in the view but display the title when the user chooses View - Customize.

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

168 Application Development with Domino Designer 7


Note that long titles do not wrap on the Web. To prevent line wrap on the Web, specify 1 in the ″Lines
per heading″ setting in the View Properties box. Domino converts this setting to a NOWRAP HTML
attribute. Specifying a number greater than 1 causes lines to wrap on the Web. The same guidelines are
true for the ″Lines per row″ setting.
v 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.

Setting styles for columns


When you create a column, you can set a variety of display options. These options are available from the
Basics tab of the Column properties box.

Style Description
Title See ″Adding titles to columns.″
Width Determines how many characters fit in one column.

(Optional) Select ″Resizable″ to allow users to change the width as needed.

You can also click the column and drag the column divider line to the width
you want.
Note: The first two columns in a calendar view cannot be marked as
resizable.
Resizable Allows a user to change the size of the column. Uncheck this if you want a
fixed-width column.
Show responses only Turns off the display of main topics and displays responses only.
Display values as icons Displays an icon associated with a numeric value you supply.

See ″Displaying an icon in columns″


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

If you choose new line as a separator, make sure you adjust the number of
lines/row to accommodate the values or they will not all display.
Use value as color Allows you to programmatically apply an RGB color to column text.

When this is checked, ″User definable″ is available to allow users to specify


colors. This requires an entry in the ″Profile document″ field.

See ″Examples: Adding programming to columns″


Editable column Allows users to edit or create documents from a view. The column value
must be an editable field for this option to be available.

For an example of this, see the calendar view in the R6 mail template. Users
can edit calendar entries without opening a document.
Do not display title in column header Use this option for suppressing the column title -- for example, when you
want a column to display icons. This also makes it easier for users to
customize columns that do not display titles. If you designate the column as
a resizable column, the title will display when the user chooses View -
Customize.
Show twistie when row is expandable Displays collapse and expand icons for a categorized view. In the Notes
client, you can supply your own image pair to create a customizable twistie.

For details on creating the images for customizable twisties, see


″Customizing the expand and collapse icons″.

Chapter 8. Designing views 169


Formatting date and time columns
To format values that result in a time or date displaying in a column , select the Advanced Format tab of
the Column Properties box and choose Date/Time as the Style.

When you select ″Use preferences from User’s settings,″ the format for dates and times depends on
display settings for a computer’s operating system. You can select a subset of display options to format
date and time values in a column. When you select ″Use preferences from Custom,″ you have more
control over how dates and time display. In addition to the settings in the table that follows, you can
override the date and time formats set by the operating system with formats you specify. In this case,
specifying a date with a format of day/month will always display the date in that format, even on a
computer where the operating system default is a month/day format.

Option name Selections Description


Display Date All If you do not want the entire date displayed, you can select a
subset of the date information. Deselect ″Display date″ if you
Only month, day and year only want time information displayed.
Only weekday, month and day

Only month and year

Only month and day

Only year

Only month

Only day

Only weekday
Special None Provides special instructions for displaying the date. Select
None to use the default format. Show ″today″ substitutes the
Show ″today″ when word ″Today″ for today’s date.
appropriate

Always show 4 digit year

Show 4 digit year for 21st


century

Show year only if not this year


Date format month/day The option is available if you have selected ″Use preferences
from Custom.″ They are not available if you have selected
month/year ″Use preferences from User’s settings.″ If you have an
international date format set in your operating system, these
month/day/year choices change. For example, they may change from
month/day to day/month.
Display Time All If you do not want the complete time value displayed, you
can select a subset of information. Deselect ″Display time″ if
Hours, minutes, and seconds you only want date information displayed.
Hours and minutes

Hours only
Time format hour:minute If you have an international time format set in your operating
system, these choices change. For example, from 02:30
hour:minute:second changes to 14:30.
All ″All″ is only available if you have selected ″Use preferences
from Custom.″

170 Application Development with Domino Designer 7


Option name Selections Description
Time zone Adjust time to local zone ″Adjust time to local zone″ displays the time relative to the
time zone of the reader. A document created at 3:00 PM 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
PM.″
Always show time zone ″Always show time zone″ displays the time zone where the
document was created. With this option, the creator’s time
zone is always shown. If a document is created in New York
at 3:00 PM, 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 ″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 PM 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.″

Displaying numbers in columns


To format values that result in a number displaying in the column, select number as the style in the
Advanced Format tab of the Column Properties box.

When you select ″Use preferences from User settings,″ the format for numbers depends on display
settings for a computer’s operating system. You can select a subset of display options to format number
values in a column. When you select ″Use preferences from Custom,″ you have more control over how
numbers display.
v Decimal formatting displays numbers as they are entered; zeroes to the right of the decimal point are
suppressed. For example, 6.00 displays as 6. You can specify a fixed number of decimal places to
display (up to 15 places) or select varying to display a number as entered.
v Percent formatting displays numbers as a percentage. For example, .10 displays as 10%.
v Scientific formatting displays numbers using exponential notation; for example, 10,000 displays as
1.00E+04.
v 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 by default on
settings in your operating system. To override those settings, choose Custom in the ″Preferences for
display formatting″ section. You can then specify formatting and display options such as a currency
symbol and thousands separator.
v Select ″Parentheses on negative numbers″ to display negative numbers enclosed in parentheses; for
example, display (5) instead of -5.
v Select ″Punctuated at thousands″ to display large numbers with the thousands separator; for example,
1,000 in English, or 1.000 in French.

Enabling a column for instant messaging


You can enable a column in a view of a Notes application so that the names of Lotus Instant Messaging
users listed in the column display their online status and are available to the user for chats. For an
example of this, see the Inbox folder of the Notes mail template.

This feature is not supported in Web applications.


1. Create a column and assign it the Names style on the Advanced Format tab of the Column Properties
box.
2. Check the options for ″Column contains a name″ and ″Show online status.″

Chapter 8. Designing views 171


3. Enter a column formula that evaluates to a name in the abbreviated form of the full hierarchical name
-- for example, Jill Patton/ACME/US. This name is required as a look-up value to retrieve a user’s
instant messaging status.

Note: Online status only displays for a single name displayed in a column. You can define a field to
accept multiple values, but if more than one name displays in a column, status icons do not display.

Tips
v Users can see the online status icons for names that you enable for online awareness if the User
Preference ″Show Instant Messaging Status″ is enabled for their client. If this preference is disabled, a
user will need to click a name to see if the user is available for chat.
v If you do not want to display the abbreviated hierarchical name in the column a user sees, you can
create a column that displays a user’s short name and link that column to a hidden column containing
the abbreviated hierarchical name using the hidden column’s programmatic name. Using this
technique, the user sees the short name, but the lookup is done using the abbreviated hierarchical
name, reducing the likelihood of ambiguous names.

Advanced options for columns


The Advanced tab of the Column properties box provides you with the options for programming a
column or for displaying the column values as links on the Web.

Assigning a programmatic name for a column


The Name field displays a default name assigned to the column for referring to the column in a script or
formula. You can edit this name to make it more descriptive. Take care editing a name assigned to a
column if you have already created formulas using the programmatic name -- changing the name breaks
all formulas that use the name.

You will need the programmatic name for the column to program the InViewEdit event that allows users
to edit documents from the view. For more information on this feature, see ″Allowing users to edit or
create documents from a view.″

Using the programmatic name assigned to columns by simple functions


If you first define a column using a simple function, then you create another column that depends on the
value of the first, you must edit the programmatic name of the first column to something other than a
dollar symbol ($) and a number. If you put $1 in a formula, it is evaluated to = the quantity/value of 1. If
you put ″$1″ in the formula, it is treated as a string rather than a variable, field or column name.

For example, if the first column in the view is the author (simple function), with a programmatic name of
$1 and you want the second column to display something based on the value in column 1, you can
change the programmatic name of column 1 from $1 to $one and then refer to the new programmatic
name in the formula for column 2. For example: @if($one = ″Mary Stone/Acme″;″READ THIS″; ″ignore
this″)

The following column names assigned by simple functions are restricted -- that is, you cannot use their
programmatic name in a formula: # in View column, Collapse/Expand, # Responses, or # Response
levels.

Using a hide-when formula in a column


Use a hide-when formula to hide a column based on conditions in place when the view first displays. For
example, to hide a column from a particular user, click the Advanced tab on the Column Properties box,
check ″Hide column if formula is true,″ and enter formula:
@If(@Name([CN];@Username) = "John Smith")

Note that because the formula evaluates when the view first displays, a hide-when formula that matches
a certain condition will fail if the condition is met subsequent to opening the view.

172 Application Development with Domino Designer 7


CAUTION:
Hide-when formulas are not a security measure. Users can still get information by viewing the
document properties. Use this feature as a method for controlling the display of information in a view.

Note: Because the ability to selectively hide a column based on a formula is new in Designer 6, columns
hidden in this way will display in earlier releases of the client unless you also check the option ″Hide in
Notes R5 or before.″

Hiding a column from R5 clients


When you check ″Hide column″ in Lotus Domino Designer 6 or later, the column will also be hidden
when the application is accessed by an R5 client. If you check ″Hide column if formula is true″ in
Designer 6 or later, the column will be visible when accessed by an R5 client because R5 did not have the
ability to selectively hide columns. If you are using the option to ″Hide column if formula is true,″ check
the option ″Hide in Notes R5 or before.″

To display column values as links in Web applications


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

Adding programming to columns


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

Chapter 8. Designing views 173


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

Field
Field lets you populate the column with certain types of field values without writing a program. This
technique works with text, number and date fields.

Formula
Formula lets you create a program for a column using the @function formula language. This is useful
when you must process values in a document (such as changing field values to a text value) or calculate
a value. Typical uses for formulas include converting field data to a text value (because only text values
display in columns), writing a formula that displays an icon instead of a value, and adding text to field
values.

Click the Field button or the Simple Function button to paste fields, @functions, or @commands into the
formula. Always convert information to the data type that your formula expects. For example, to append
a numeric value to a text value in a column, use a formula like:
Product + ": " + @Text(Quantity)

Examples: Adding programming to columns


The following examples illustrate some common column programming techniques.

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

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

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

Combining text and names: The following formula results in three possible results, based on the status
of a request:

@If(Status=″Rejected″;″Rejected by ″ + LastApproveName; SignatureCount=0; ″Original


Request″;″Approved by ″ + LastApproveName)
v If the request has been rejected, the column displays ″Rejected by″ and the name of the person who
last signed the form.
v If the request has no signatures (meaning that no approver has acted on the request), the column
displays ″Original Request.″

174 Application Development with Domino Designer 7


v If the request has been approved, the column displays ″Approved by″ and the name of the person who
last signed the form.

Showing when a document was created: The Created column in the By Author view of the Document
Library template uses the following formula to display the date on which the document was created:
@Created

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

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

Creating ″fake″ indenting: When Notes indents response documents, the indentation is always the
same. If you want to make a document in a flat view appear indented without using response
documents, or display document titles in the same column at different indentations, you can use a field
on the form to determine how much each document indents and use a column formula that appends
space characters to the document titles in the view. The following formula ″indents″ documents in three
different ways depending on the value in the Indent field. For example, if the value of the Indent field is
2, 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 author’s category:
@IsCategory("";@DocNumber("") + ". ")

If the row is a category (the author’s name), @IsCategory returns a null string (″″). If the row isn’t a
category, then the row represents a document, and @DocNumber returns a string that represents the
entry number of the document. The document’s 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.

Setting column colors programmatically: In Notes client applications, you can set a column’s
background color and text color programmatically by selecting the ″Use value as color″ option on the
Info tab of the Column Properties box and then supplying RGB coordinates in the Programmer’s pane as
the value for the column.

Note: This feature is supported on the Web, but you must supply the RGB coordinates of the color as a
number list (e.g. 255:0:255). Text color values (e.g. ″FF00FF″) are not supported.

If you specify one set of coordinates (three numbers separated by colons), the color defines the
appearance of the text. If you specify two sets of coordinates (six numbers separated by colons), the first
set of coordinates defines the background color for the column, and the second set of coordinates
specifies the text color. The color affects the column where you set the color value and all columns to the
right of that until another color is set.

Note: Setting colors to -1:-1:-1 reverts to the view and column properties.

For example, the following formula example shows how RGB coordinates can be used in both single and
paired sets.

Chapter 8. Designing views 175


red := 255:0:0;
blue := 0:0:255;
yellow := 255:255:0;
pink := 255:193:253;
white := 255:255:255;
black := 1:1:1;
apricot := 255:155:133;
plain:= 0:0:0;
@If (category = "cats";blue:red ;subcategory = "collars";pink;subcategory ="leashes";black:plain;0:0:0);

Note: You do not need to define the color names -- you can enter the numeric combinations directly into
a formula. However, defining the colors makes it easier to see what you are doing and reduces the
possibility of a typing error if you are using the same color more than once. While defining the colors
makes it easier for you to use words rather than number combinations, the color column sets does not
display the data itself. To display the category ″cats″ in red, for example, you would need a subsequent
column that is set to display the category.

You can also set the column value equal to a field value that supplies RGB coordinates. You can use this
feature in conjunction with the color field to allow a user to set a color with a color picker. You can then
apply that color to a view component -- for example to the text in a column. For information on using
this feature to make view colors customizable, see ″Allowing users to set colors in a view.″

Table of simple functions for columns


The following simple functions (that is, functions that let you add programming without knowing a
programming language) can be used with columns.

Function name Description Example


Attachment Lengths Displays the file size of document
attachments. The data type is a number
list.

Attachment Names Displays the file names of document


attachments. The data type is a text list.

Attachments Displays the number of files attached


to each document. The data type is a
number.

Author(s) (Distinguished Displays document author name in


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

176 Application Development with Domino Designer 7


Function name Description Example
Collapse/Expand (+/-) Use in a column styled as a
Sorted/Categorized column or one
displaying documents which have
responses. 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 document is 1.1.

# of Responses Displays the number of direct


descendant (response) documents for a
(1 Level) document or next-level subcategories
for a category.

Chapter 8. Designing views 177


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

Displaying an icon in a column


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

An icon column has two requirements:


v You must select the column property ″Display values as icons.″
v You must use a column formula that results in a number that corresponds to the icon you want to
display from the table of predefined icons, or you must enter the name of an image resource as the
value for the column.

Displaying a predefined column icon


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

Use 0 as the ″false″ case when you want to leave the column blank. The formula above returns 0 when
the document has no attachments, so nothing is displayed. A column can display multiple icons, so in
this example you might replace the 0 with a different icon value, or use nested If statements to establish
conditions for displaying various icons. A column can display up to 10 different icons. All of the icons
must be predefined icons. Domino cannot display predefined icons and custom icons in the same column.

Displaying a custom icon


To display a custom icon, create the icon as an image resource, then enter the name of the image resource
as the default value for the column. For example:
"logo.bmp"

An image resource can be a GIF, BMP, or JPEG graphic. The recommended size for a column icon is .2
inches wide and .18 inches high. For information on creating an image resource, see ″Creating an Image
Resource.″

A column that displays icons can’t display anything else, such as a plus (+) sign for an expandable
categories column. Also, a column can only display one type of icon -- either a predefined column icon or
a custom icon, but not both.

Note: Icons are accessible to vision-impaired users who use screen reader software. The software ″reads″
the string names of the icons. Custom icons display on both the Notes client and Web client.

178 Application Development with Domino Designer 7


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 10. The value for any icon in the rest of the columns starts with the
number shown in the column heading, for example 41, and increments by 1 for each row in that column.

Accessibility tips for view icons


For enhanced accessibility and usability of applications, when a user hovers the mouse pointer over a
view icon, the icon image name displays. This feature is enabled as a user preference on the Notes client.

The following are some guidelines to consider when using view icons in an application:
v If you designate an existing view icon by number, the default icon description displays.
v When creating custom icons for use in view columns, assign meaningful image names because the
names will be used as the hover text.
v If there are multiple icons in a column, hovering the mouse pointer over the icons displays as many
icon descriptions as will fit across the user’s screen.

Sorting documents in views


Most views can benefit from 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.

Ascending and descending order


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

Character sorting rules


After the ascending or descending order is set, characters are sorted in this order:
v Numbers
v Letters

Chapter 8. Designing views 179


v Accented letters
v Punctuation/special characters

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

Sorting multiple values


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 don’t set this option, multiple values display as one
entry.

CAUTION:
If you set this option on a column that displays a multivalue list, but you do not specify a sort order
for the column, Designer displays only the first value in the list. Also note that setting this option for
multiple columns in a view can have a serious performance impact on your application.

Setting this option correctly on a sorted column may still not produce the results you are expecting. In
the following example, Julie has created a document with a field containing the items apples and
chickens. Bill has created a document with a field containing the items bananas and ducks. When you
sort the Entry column in ascending order and specify ″Show multiple values as separate entries,″ the
following view results:

To list multiple entries from a document together, you must sort a column to the left. In this example,
sorting the Author column creates the following display:

And finally, to streamline the display, you can categorize the Authors column to produce the following:

180 Application Development with Domino Designer 7


Displaying a categorized view as flat
If your view is a categorized view built in Designer Release 5.0 or later, you can select ″Categorized is
flat version 5 or greater″ to convert your view to a non-hierarchical, flat view, which displays all
documents on a single level. Use this feature if your level of indentation in a view exceeds the limit of 32
levels.

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

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

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

Multiple sorting columns


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

Chapter 8. Designing views 181


Using an auto-sorted column as the secondary sorting column
To add a secondary sorting column, add a column to the right of the first sorting column and then
choose Sort: Ascending or Sort: Descending on the Sorting tab of the Column Properties box. Documents
and responses are sorted, then sub-sorted, in column order from left to right.

Designating a secondary sorting column for a user-sorted column


User-sorted columns override the sorting built into auto-sorted primary and secondary columns. If the
view has a user-sorted column and you want to include secondary sorting, you can associate it with a
secondary sorting column. On the Sorting tab of the Column Properties box for a user-sorted column,
click ″Secondary sort column″ and choose the secondary sort column and its sorting order.

Overriding alphabetical sorting with a hidden column


The sorting column does not need to be visible. Sometimes you may want to use a hidden column as
your sorting column. To hide a column, check the Hide box on the Advanced tab of the Column
Properties box.

For example, a Service Request form contains a Priority field, which uses the following choice list:
Urgent
High
Medium
Low

You want the By Priority view to sort documents by the value in the Priority field, but you don’t 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:


v Is hidden
v (Optional) Has no title
v (Optional) Is one character wide
v Uses this formula to determine the order of each priority:
@If(Priority="Urgent";"1";Priority="High";"2";Priority="Medium";"3";"4")

182 Application Development with Domino Designer 7


v Is sorted in ascending order

You add a column to the right of the hidden column that:


v Is not hidden
v Has the title ″Priority″
v Is 10 characters wide
v Displays the value of the Priority field
v Is not sorted

Using a column to switch to another view


To give users an easy way to see additional, related information that doesn’t fit in the initial view, use a
column as an entry point to another view. Users click such a column to open another view. To set this
option, choose ″Click on column header to sort″ on the Sorting tab of the Column Properties box and
choose ″Change to view″ as the sorting option. 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.″

Generating column totals, averages, and percents


To display totals, averages, or percents for a column’s 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.

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.

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 values of 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 subcategory 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 category’s percentage as it relates to the overall view total.

Percent of all documents calculates a total for all documents. For each category, Notes displays the
category’s percentage as it relates to the overall view total.

To display totals without the clutter of extra numbers, select ″Hide detail rows″ to suppress numbers
other than totals or subtotals for each category and subcategory.

Setting styles for a standard view or folder


To make a view or folder attractive and easy to use, consider the layout of the view or folder and its
columns and rows. View or folder, row, and column properties work together to display colors, widths,
fonts, and so on. These view/folder style options are available from the Style tab of the View/Folder
properties box.

Chapter 8. Designing views 183


Option name Description
Body Choose a color for the view background. To set alternate colors for rows in a view,
choose an ″Alternate rows″ color.

Use ″Image″ option to specify an image resource as a view background for Notes client
users. Choose one of the ″Repeat ″options to display a single copy of the image or to
tile multiple copies of the image for the view background.

Can also specify a formula for displaying an image based on a certain condition. The
formula evaluates when the view first displays. Avoid using an animated GIF file.
Grid Specify a grid style for the view. Use ″Color″ option to set a color for the grid lines.
Note: Non-resizable columns and response only columns do not display gridlines.
Categorized views, views with flat headings, and views with simple headings only
display horizontal gridlines.
Header Shows a bar at the top of the view with column titles in a beveled, flat, or simple look.
Beveled--background is gray; Simple--background matches view color. Use the ″Color″
options to set a color for the header. Use the ″Height″ option to set a header height from
one to five lines to specify how many lines a column title can wrap. Useful for long
column titles or instructions placed in a column title.
Rows Specify how many lines a column can contain. Increase this value if you are using
newline to separate multiple values in a view. ″Shrink rows to content″ and setting a
color for alternate rows are useful accompaniments to multi-line rows. ″Row spacing″
sets the vertical space between rows in a view. Default is single-spaced rows.

″Don’t show categories″ suppresses the display of categories with no documents.


″Colorize view icons″ colors the pre-defined Domino view icons to match the header
color.

Color options let you set colors for unread documents and for column totals. Red is
used in Domino templates for unread documents. Since Bold does not display in R5
clients, you can specify an Unread color and check the ″Transparent″ option so that R5
users will see unread rows in a color while Notes Release 6 and later users see unread
rows as bold.
Other Shows the document selection margin. Deselect for cleaner-looking rows. If you deselect
″Show selection margin,″ users can still select documents by pressing and holding
SHIFT as they click document names. The selection margin appears temporarily while
documents are selected, and hides again when all documents are deselected.

″Hide selection margin border″ turns off the border separating columns.

″Extend last column to window width″ fills out the last column to avoid empty space in
the view. This makes view easier to read.
Margin Sets margins for a view in pixels (1 to 100.) If you deselect ″Show selection margin,″
users can still select documents by pressing and holding SHIFT as they click document
names. The selection margin appears temporarily while documents are selected, and
hides again when all documents are deselected.

Use ″Color″ to set a color for the view margin. Useful for off-setting a view with a
contrasting background color.

Display options for views


The Options tab of the View Properties box determines the initial display of a view and specifies how
users can access and interact with the view.

184 Application Development with Domino Designer 7


Setting the view as the default
If you want a view to be the first view displayed when the database opens, check the ″Default when
database is first opened″ option. This only applies the first time the user opens the database. Subsequent
openings by the same user display whatever is set on the Launch tab of the Database Properties box.

Using a view or folder as a template


If you want a view or folder to serve as a template, or model, for other views and folders that you design
in the same database, check the ″Default design for new folders and views″ option.

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

Organizing response documents in a hierarchy


In an application such as a discussion forum, if you want response documents displayed in a hierarchy,
with each level of response indented from its parent, check the ″Show response documents in a
hierarchy″ option. Otherwise, responses will display at the same level as the main topics. If this option is
checked but the view only contains response document, no documents will display. Response documents
are only visible in hierarchical views when the parent document is displayed.

Adding a view name to the View menu


To make the view available to users from the View menu in Notes, check ″Show in View menu.″ In
addition to this, or in place of in Web applications, you should provide another means of accessing the
view, such as an action button, or a link from an imagemap or outline.

Allowing Notes users to customize a view


By default, a Notes client user can customize a view in a variety of ways, including resizing and
reordering columns or setting color options. Changes users make are maintained when they close and
reopen the view. If you do not want users to customize a view, deselect the ″Allow customizations in a
view″ option on the Info tab. Note that deselecting the option does not disable the user menu option to
customize the view. It does, however, disable all the options within that dialog except for sorting. Sorting
is retained as an available item for accessibility purposes.

Note: This feature is not supported on the Web.

Evaluating formulas when documents change


A view can have associated actions, such as show/hide formulas, that evaluate when a view is opened.
There may be cases when you want an action to evaluate every time a document changes in a particular
view. For these cases, check ″Evaluate actions for every document change.″ Be aware that checking this
option can have a serious impact on the performance of your application.

Creating new documents at view level


Check this box if you are enabling a view so that a user can create a new document from the view level.
In addition to enabling this option, you need to program the InViewEdit event for the column to specify
what should happen when the Notes client user creates a document.

For more information, see ″Allowing users to edit or create documents from a view.″

Opening to a particular row in the view


To highlight a particular row when a user opens the view, click ″On Open″ in the Options tab and select
one of the following from the list:

Chapter 8. Designing views 185


v Go to last opened document (the default choice)
v Go to top row
v Go to bottom row

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 isn’t available for views opened by Web users.

Refreshing a view
The On Refresh options let you specify what a user sees when a view is refreshed. For more information,
see ″Refreshing view indexes.″

Page breaks in a view


You cannot set page breaks for a view.

Adding categories to views


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

To categorize a view
1. Create a column to display categories.
2. Select the option ″Type: Categorized″ on the Sorting tab of the Column Properties box. Choose a sort
order of Ascending or descending. (Ascending order organizes the categories in alphabetical order
and descending order in reverse alphabetical order.)

186 Application Development with Domino Designer 7


The resulting column, called a categorized column, groups documents with matching values and
converts the common value to a category name. The column is usually one that appears on the left
side of the view. This column must always appear to the left of any sorted columns.

Other options include:


v (Recommended) At the Font tab of the Column Properties box, choose a different color for column text
and use bold face to make categories stand out.
v (Recommended) At the Column Info tab of the Column Properties box, select ″Show twistie when row
is expandable″ to display a triangle that users click to see categorized documents.
v (Optional) At the Options tab of the View Properties box, select ″Collapse all when database is first
opened″ to show only the category names when users open the view.
v (Optional) At the Style tab of the View Properties box, select ″Don’t show empty categories″ so that
categories without documents are not listed.

Generating category names


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

Setting up a Categories field


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

To categorize documents created with the form, choose Actions - Categorize.

Setting up categories in advance


To set up a predefined list of categories, create a computed choice list field and enter the category names
as its values.

Converting choice list field aliases to full category names


If you base a categorized column on a choice list field that contains aliases for the fields, those aliases are
used as the category names.

For example, a RequestType field that contains the following choice list fields displays the category
names as HW, SW, and SVC:

Hardware Request | HW

Software Request | SW

Service Request | SVC

To display the full names of a choice list field that uses aliases, use a hidden field or column formula that
converts the aliases back to their full names:
@If(RequestType="HW";"Hardware Request";RequestType="SW"; "Software Request";"Service Request");

Letting users create categories in the Categorize dialog box


To let users enter their own categories in the Actions - Categorize dialog box, include an editable,
multivalue, choice list field called ″Categories″ on the form and select the field option ″Allow values not
in list.″

Chapter 8. Designing views 187


Generating dynamic lists of categories
To generate dynamic lists of categories, create a choice list field named Categories. Then, use the
@DbColumn formula to calculate values for the field.

Categorizing in the All by Category view


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

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:


v Users have access to response forms, whose types are Response and Response-to-Response.

188 Application Development with Domino Designer 7


v ″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
v The view has a responses-only column. Create the responses column directly to the left of the column
under which responses are to be indented. Leave its title blank, make its width 1, and select ″Show
responses only″ in the Column Info tab of the Column Properties box. Write a column formula that
displays information about the response documents shown in the column, such as their authors or
creation dates.

Tip: You should create only one response column in a view.

Formulas for response columns


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

Tip: You should create only one response column in a view.

Including information about the author


A discussion database could show the response document author, date, and subject line with this
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 they’ve 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)")

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)

Chapter 8. Designing views 189


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 haven’t read it yet.

Choosing a style for unread marks


These options are set as a design property for a view. Open the Advanced tab of the View Properties box,
and select an ″Unread marks″ option.

You can display unread marks as:


v ″Standard (compute in hierarchy)″
Displays asterisks for unread main documents and response documents and for any collapsed
categories containing unread main or response documents.
v ″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.

Choosing a color for unread marks


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

Checking the Bold property for unread rows displays unread documents in bold. Note that Lotus
Domino Designer R5.x does not support bolding of unread entries, so they will appear in a plain font for
R5.x users. To highlight unread documents in R5 while using bolding to highlight them in R6, select a
color for unread marks (which will be visible in R5) and then choose the Unread Transparent option to
make the color transparent to R6 users (causing them to just see the bold font).

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 don’t 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.

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.

190 Application Development with Domino Designer 7


Allowing users to edit or create documents from a view
You can give Notes users the ability to edit fields in an existing document or create a new document
from a view. For example, you might use this feature in a ToDo view to change a work item from
Incomplete to Complete. The Domino mail template uses this feature to allow you to enter an
appointment into your calendar from the calendar view.

Note: This feature is not supported for Web users.

Usage Notes
v InViewEdit events will work for embedded views as long as the ″Selection tracks mouse movement″ is
not checked on the Display tab of the Embedded View Properties box. InViewEdit events are not
triggered in an embedded view if this feature is enabled.
v This feature is not supported in views from another database that are embedded in a rich text field.
For example, trying to create or edit a document in a view from a discussion database embedded in a
mail message results in an error.
v The InViewEdit event works for folders as well as for views. However, if a user presses Ctrl-Click to
create a new document in a folder, the new document is created, but is not put into the folder. Instead,
it will appear in views for which it meets the selection criteria. As with other cases, the document must
be explicitly dragged, moved, or added to the folder.

Note: Users will be prompted to Ctrl-Click to create a document when there is at least one document
already in the view. If the Ctrl-Click line on a view is not entirely visible, and there is no vertical
scrollbar to scroll down further, users can press Ctrl-End to make it more visible.

To allow users to edit documents in a view


To let users edit an existing document without first opening the document, you must first identify the
columns containing user-editable fields. Then you must supply code that controls what a user can do
when editing the associated field. You can mark more than one column as editable. For each column you
want to allow the user to edit:
1. Select the column that will display the editable field.
2. Choose Design - Column Properties.
3. Check ″Editable column″ on the Info tab (i) of the Column Properties box.
4. Click the Inviewedit event in the View objects list in the Programmer’s pane.
5. Enter code to control what should happen when a user edits the field, as described in the
programming topic InViewEdit event.

To allow users to create a new document from a view


1. Select the view from which users can create new documents.
2. Choose Design - View Properties.
3. Check ″Create new documents at view level″ on the Info tab (i) of the View Properties box.
4. Click the Inviewedit event in the View objects list in the Programmer’s pane.
5. Enter code to create the new document, set the form value and to check and validate entries for the
new document, as described in the programming topic InViewEdit event.

Coding notes
v There is only one InViewEdit event per view. The event is called multiple times for each edit and uses
a parameter called RequestType to determine whether Notes should be providing default information,
validating data, or saving changes to documents in the view.
v More than one column can be marked as user-editable.

Chapter 8. Designing views 191


v Use the programmatic name as set in the Advanced tab of the Column Properties box as the name of
the field that gets updated when the column is edited. This will make coding the InViewEdit event
easier to identify the column you are marking as editable.
v Code the RequestType parameter with a value of 4 to handle document creation.
For a complete description of how to code the InViewEdit event, see the Lotus Domino Designer
Programming Guide.

Allowing users to set colors in a view


Designer allows you to set the color for a column programmatically to visually differentiate documents in
a view. You can use this functionality to provide users with the means to set the color for documents in a
view. This feature can be extended to allow users to determine the colors for a column by means of a
generic profile -- a particular type of form -- to set values in a database. For example, in the Lotus
Domino Release 6 mail template (mail6.ntf) you can choose Tools -- Preferences, click the Colors tab and
associate colors with different senders to customize how mail displays in your Inbox.

Note: Because it relies on a generic, rather than a user-specific profile form, the feature is only useful for
a database with only one user, such as a mail database or a personal journal.
1. Create a profile form in the database that creates one profile for the database. Make sure you create a
button, action, or agent that users can run to create the profile document.
For information on creating a profile form, see ″Creating a profile form.″
2. Create two fields on the profile form. The first will be a color field that users will use to select a color.
The second field will be a formula field set to hold either the value of the color field, or a formula
that evaluates to a color. The formula field must have the same name as the programmatic name for
the column in the view. For example, if the column’s programmatic name is ″$3″, then the formula
field on the profile form must also be ″$3″.

Note: If you want the user to be able to set both a text color and a highlight color, you will need two
color fields, and the $3 field will need to combine the two colors.
For information on creating a color field, see ″Color fields″ in the chapter ″Designing Fields.″ For
information on the programmatic name for a column, see ″Adding programming to columns″ in this
chapter.
3. Select the view column you want to make customizable and choose Design - Column properties.
4. On the Column Info tab, check ″Use value as color″ and ″User defined.″
5. In the field next to ″User defined,″ enter the name of the profile form.
6. In the programming pane, choose ″Formula″ as the column value and enter a valid formula, such as
@UserName, as the column formula.

Setting the color value in the profile document


To specify a color for a column, the user must create a profile document without a user name. Since this
special type of form cannot be created using the Create menu, you must supply a button, action, or agent
the user can use to create the document. When the document is created, the user sees a color picker for
the specified column.

For information on creating and editing a profile document, see ″Profile forms″ in the ″Designing Forms″
chapter.

Formulas that look for values in columns and views


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

192 Application Development with Domino Designer 7


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 backslash (\) 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. Refresh the view
to make sure you see all its columns.

Some columns are not counted in a search, so skip them when you’re counting column numbers:
v Skip any columns that display a constant value.
However, if a column contains a formula that happens to return the same result for every document
(so that it appears to be a constant value even though it is not), the column does not display a constant
value. Include the column in your column count.
v Skip any columns that consist solely of the following simple Notes functions or @functions:
Collapse/Expand (+/-)
# in View
# of Responses (All Levels)
# of Responses (1 Level)
@DocChildren
@DocDescendants
@DocNumber
@DocParentNumber
@DocSiblings
@IsCategory
@IsExpandable

If you plan to use a lookup formula, such as @DbColumn or @DbLookup, to retrieve data from a view,
include a sorted column that the formula can use as the lookup key.

Creating a calendar view


In a calendar view, documents that are created using a form designed for scheduling individual meetings,
appointments, events, and the like, display as entries on a calendar. For an example of a calendar view,
see the R6 Mail template (mail6.ntf) $Calendar view, and for an example of a calendar form see the form
_Calendar Entry. It is best to create the form first, and then create the calendar view to display the
documents created using the form.

To create a calendar view


You begin by creating a standard outline view. You can either complete Steps 1 through 10 for creating a
standard view or you can convert an existing view to a calendar view.
1. Create a new view or open an existing view.
2. Open the View Properties box.
3. In the Style field, select Calendar. A dialog box appears. Click yes to continue.
4. Click the first column. In the Column properties box, select ″Hide column.″

Chapter 8. Designing views 193


The first column of a calendar view defines the Date/Time the entry will display and should be
hidden.
5. In the Programmer’s pane, choose one of the following and enter a value for the first column that will
evaluate to both a date and time:
v Simple function - Select a value from the list that evaluates to a date and time -- for example,
″creation date.″
v Field - This displays a list of all the fields in the database. Select a date/time field from the form
you will use with the calendar view.
v Formula - Write a formula in the Programmer’s pane that evaluates to a date and time.
6. Open the Column properties box and click the Sorting tab. Choose the sort option Ascending.

Note: If you have a field on your form that allows multiple values, and you want each value to
display as separate entries in the calendar view, select the column sorting option ″Show multiple
values as separate entries″ for the first column. For example, the Mail template uses this technique for
displaying repeating events. Otherwise, the entries display under the first matching date only.
7. Click the Date and Time tab of the Column properties box and check the Display Date and Display
Time options.

Tip: The column settings for this column allow you to specify ″Always show time zone,″ but this
setting (along with the other column display settings) is not used by the calendar display. If you want
the time zone to always be displayed, add another (visible) column to the view and put the time zone
information in that column.
8. Create a second column or click the second column of the existing view. The second column must
map to a field or formula on the document that specifies, in minutes, the duration of the event and it
should be hidden. In the Column properties box, select ″Hide column.″
9. Create a view selection formula that will select the documents to be displayed -- for example,
_Calendar Entry.

Formatting options for calendar views


Once you create a calendar view, you can format it. Click the Date and Time format of the View
properties box. The Date and Time format tab appears only when Calendar is selected for the view style.
On the Date and Time tab you have the following display options.
v Calendar formats available to users
Check all of the display options you want to make available for users to select. For example, if you
want to give the user the choice to view the calendar in a one month format or a one day format,
check those two options. Note that the ″Work calendars″ option includes one work week, two work
weeks, and the work month formats. These are weeks that display without Saturday and Sunday.
v Initial format
Sets the format displayed to the user when the view first opens.
v Time slot display available to users
A time slot is a graphical display of time periods in the view. If ″Time slot display″ is selected, time
slots appear in the view. If you select this option then you must choose a start and end time for the
time slots as well as the duration -- for example, one hour. If you select the option ″Users may override
these times,″ the user’s Notes client calendar preference determines how time slots are displayed in the
calendar.
The option ″Users may toggle time slots on/off for each day lets a user display and hide time slots for
a selected day.
v Other options
In weekly and monthly views, ″Group entries together by time slot″ clusters entries under time slots
instead of listing entries for a day. For example, if you have two entries for 12 PM and one entry for 1
PM, the different displays are as follows:

194 Application Development with Domino Designer 7


Group entries checked Group entries unchecked
12:00pm Appointment 1 12:00pm

Appointment 1 Apppointment 2 12:00pm

Appointment 2 Appointment 3 1:00pm

1:00pm

Appointment 3

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.
v Check the selection formula for the view. Make sure the documents you want to display in the view
match the selection formula. To test the selection formula, change the view to a standard view or
refresh the view while in Designer. If the documents display, the selection formula is valid.
v Make sure the first column of the view is based on a Date/Time field and is sorted in ascending order.
Display the documents in Designer to test the view. Both the date and time should display. The
documents should display first sorted by date, and then for each date, sorted in chronological order, so
that a 9 AM appointment displays before a 3 PM appointment on the same day.

Setting styles for a calendar view


Calendar views have different style options than standard views. Use the options on the Styles tab of the
Calendar view properties box to enhance the presentation and usability of your calendar view.

Option name Description


Body Choose a color for the view background and the grid lines.

Use ″Image″ option to specify an image resource as a view background for Notes client
users. Choose one of the ″Repeat ″options to display a single copy of the image or to
tile multiple copies of the image for the view background.

Can also specify a formula for displaying an image based on a certain condition. The
formula evaluates when the view first displays. Avoid using an animated GIF file.
Header Specify the type of header you want for the calendar view. Choose ″None″ for no
header, ″Plain″ for simple labels with lines between them, or ″Tabs″ for a tabbed display.
Use the ″Background″ option to set a color for the header. The ″Display″ list lets you
choose what header components to display. Note that you can now display the Trash
and All documents folder using this control.
Date area Choose colors for the calendar background, the ToDo area, and for today’s date. Check
the large numbers options if you want a DayPlanner look for your calendar view.
Daily When looking at a daily page, you can highlight work hours with one color and
non-work hours with another.
Monthly When the calendar is displayed in 31-day format, sets the background and text color for
days that start a new month.

Chapter 8. Designing views 195


Option name Description
Entry Choose a background color for entries and a color for unread entries. Red is used in
Domino templates for unread documents. Specify how many lines an entry can contain.
Increase this value of ″Height (lines)″ if you are using newline to separate multiple
values in an entry. ″Shrink rows to content″ automatically suppresses extra blank lines
and ″Spacing″ sets the vertical space between rows in a view. ″Show conflict marks″
displays a conflict bar when two or more entries overlap or conflict in a calendar view.
″Unread transparent″ provides backwards compatibility for R5.x users who will not see
unread marks in bold if Bold is checked. Instead, they will see them in a color you
specify if ″Unread Transparent ″ is checked.
Other Shows the document selection margin. Deselect for a cleaner-looking view. If you
deselect ″Show selection margin,″ users can still select documents by pressing and
holding SHIFT as they click calendar entries. The selection margin appears temporarily
while documents are selected, and hides again when all documents are deselected.

″Extend last column to window width″ fills out the last column to avoid empty space in
the view. This makes the view easier to read.
Margin Sets margins for a view in pixels (1 to 100). If you deselect ″Show selection margin,″
users can still select documents by pressing and holding SHIFT as they click document
names. The selection margin appears temporarily while documents are selected, and
hides again when all documents are deselected.

Use ″Color″ to set a color for the view margin. Useful for off-setting a view with a
contrasting background color.

Displaying views in Web applications


Views and folders created in Notes may not have the same features on the Web. For example, a view or
folder will display as a full screen with default navigation buttons on the Web.

To gain more control on the Web, consider using a view applet, an embedded view or folder, or an
embedded view applet. When you embed a view or folder on a form, subform, page, or document, you
maintain the same functionality available in Notes applications, and you control the size and appearance
of a view or folder display. When you define a view or an embedded view as a view applet, you
preserve much of the HTML view functionality and provide features such as resizeable columns, multiple
document selection, and scrolling.

Embedding a view or folder pane lets you combine views and folders with other form elements (such as
styled text) and graphics to create a high-impact design. The Designer templates contain numerous
examples of forms designed in this way.

If you have multiple views or folder panes you want to display in an application, you can create one or
more view templates that control how the embedded objects display. A view template is actually a special
form that provides the design structure for displaying the embedded folder panes or views in an
application.

Specifying how a view displays in a Web browser


To embed a view on a page, follow the steps in ″Creating an embedded view or folder.″

To control the display of a view in a web browser


1. Open the view in the View work pane.
2. Choose Design - View properties.
3. On the Advanced tab of the View Properties box, choose one of the following:
v ″Treat view contents as HTML″

196 Application Development with Domino Designer 7


v ″Use applet in browser″
v ″Allow selection of documents″ lets you specify whether users can select multiple documents on
the Web. Typically you would enable this if your application included an action a user might apply
to one or more documents in a view -- for example, a Move to Folder action.
For more information on displaying a view using HTML, see the topic ″Using HTML formatting for
views.″
For more information on displaying a view as an applet in a browser, see the topic ″Displaying a
view as an applet in Web applications.″

Creating an embedded view or embedded folder


When you embed a view or folder on a form, subform, page, or document, you can control the size and
appearance of a view or folder display, especially on the Web. Embedding a view or folder pane lets you
combine views and folders with other form elements (such as styled text) and graphics.

Before you begin, if there is any chance the view or folder you are embedding could be renamed, assign
an alias before you embed it to avoid breaking the application if an embedded object is renamed.

For information on naming views and folders, see ″Naming a view or folder.″
1. Open a form, subform, or page in Designer, or open a document in Edit mode.
2. Place the cursor where you want the embedded view or folder to display.
3. Choose one of the following:
v Create - Embedded Element - View
v Create - Embedded Element - Folder Pane
4. Views only: set a display option for the embedded view. You can display the view using HTML, as a
Java applet, or using the display properties set for the view.
5. (Optional, for views) You can assign a name to the embedded view. This name allows you to specify
an embedded view as a target from another embedded view. This technique is used in the Notes mail
template to show discussion threads in the Inbox view of the workplace.
6. (Optional, for views) If you don’t want to display the same view in all circumstances, click ″Choose a
View based on a formula.″ When you click OK to close the dialog box, write a formula in the
Programmer’s pane to display the appropriate view.
7. (Optional, for views) You can specify a target frame on the Info tab of the Embedded View Properties
box. The target frame specifies where the document is displayed when a user selects a document in
an embedded view with a single click or with the arrow keys, or with a double click. You can specify
a target frame for a single click (next to ″for single click″) and a target frame for a double-click (next
to ″for double click″).
For more information on target frames, see the Framesets topic, ″Specifying a target frame.″ Close and
save the form, subform, page, or document.
8. (Optional, for views) If the embedded view is in the current database, you can select ″Show only
current thread″ to display documents for one ″thread″ -- that is, one main topic and all the associated
response documents.
9. (Optional, for views) Check ″Use views selection margin property″ to maintain the margin settings
you set for the view.

Tips
v To delete an embedded view or folder pane, click the embedded view or folder pane in the Work pane
and choose Edit - Delete.
v Domino prevents the view opening if there are create or read access lists on a form in which views are
embedded.
v For compatibility with previous releases, the reserved fields $$ViewBody and $$ViewList still work on
forms.

Chapter 8. Designing views 197


v When you embed a calendar view, the embedded view property ″Disable scrollbars″ has no effect.
Scrollbars for calendars always display -- the horizontal scrollbar is used to change dates, and the
vertical arrows appear if there are too many entries to fit the vertical space.
v If you are embedding a calendar view, make sure the embedded view has enough height to display as
much of the calendar as you want displayed. The user will not have a vertical scroll bar to move lower
in the view. Also, if the embedded view is too short, the bottom footer indicating which week/month
of the year is being shown will not display.
v After embedding a view, you can change the view by clicking the Formula button in the Programmer’s
pane, then clicking the View button. You will see a list of views from the database where the original
embedded view came from. For example, if you embed the Inbox view from your mail database, then
you want to change the view, your choices are limited to the other views in the mail database. To
embed a view from a different database, you must first delete the embedded view and embed the view
you want.
v You can display a discussion thread in an embedded view from another embedded view (see the Notes
mail template for an example). Then, when a user opens the page or document, both views launch,
displaying the current document and the associated thread.
To do this, create an embedded view with threads on a page or form and assign it a name in the
Embedded View. Check the ″Show only current threads″ option on the Embedded View Properties box.
Then, create another embedded view on the page, form, or document, and in the ″Single Click″ target
field on the Embedded View Properties box for the second view, enter the name of the first embedded
view.

Setting display properties for an embedded view


After embedding a view on a page or form, you can set a variety of display properties that control what
users see.
1. Select the embedded view on a page or form and choose Element - View properties.
2. Click the Display tab and specify any of the following display properties:
v Specify the dimensions for the embedded view in the Size section.
v ″Show header″ shows the column names for the view.
v ″Selection tracks mouse movement ″moves a selection box over documents as you mouse-over
them. If this option is checked, ″show selection margin″ cannot be checked. Also, note that this
options is not available when a view is set to allow users to edit document from the view.
v ″Transparent background″ overlays the view contents on the page or form background.
v ″Show entries as Web links″ displays each view entry as a clickable link.
v ″Show Action Bar″ displays the action bar for the view for Notes client users. This feature is not
supported on the Web.
v ″Show selection margin″ adds white space around the view for Notes client users. If this option is
checked, ″Selection tracks mouse movement″ cannot be checked.
v ″Show Only Current Thread″ displays the parent and response documents associated with the
current document. This is useful in a threaded discussion database.
v ″Summarize calendar entries″ displays a calendar view in Summarize mode when the view is
launched. Once the view is displayed, a user can change the display mode for the view. If this
option is not selected, the view displays in the last state saved. This option has no effect on
standard views.
v ″Show recent first″ scrolls the view to show new messages at the top of the view rather than at the
bottom. This option is for use with mail views to force a display from newer to older messages.
3. Click the Border tab and specify display properties for the view border.

To show a single category in embedded views


You can restrict an embedded view to a single category. However, for the Show Single Category option to
work, the embedded view must first have been categorized . Note that the category name will not appear

198 Application Development with Domino Designer 7


in the embedded view. For example, if you check the Show Single Category box for a category named
Kitchen, the embedded view will not have a line named Kitchen. Instead, you will see under Kitchen
documents such as Stove, Refrigerator, and so on.

Also, if the Show Single Category formula evaluates to an asterisk (*), all categories are shown. This is
useful if, for example, you want to restrict an embedded view to a single category for Web users and
show all categories for Notes users.
1. Open a form in Designer.
2. Choose Create - Embedded Element - View. The Insert Embedded View dialog box appears.
3. Highlight the view you want and click OK.
4. Choose ″Show Single Category″ as the event in the object list in the Programmer’s pane.
5. Enter a formula to compute the category. The formula can make use of information about the current
user and information from the current document (the one embedding the view).

Note: You cannot use @Commands with Show Single Category.

To set line counts in embedded views


For embedded views, you can specify the number of lines to display in the browser. Note that the line
count property is ignored if you choose a view applet to display the embedded view.
1. Create an embedded view.
2. In the Info tab of the Embedded View Properties box, enter the number of lines next to ″Lines to
display in the browser.″
If you check Default, the embedded view acts in the same way it did in previous releases, so that the
line count value is controlled server-wide from the NOTES.INI file.

In the Web server, you can determine the number of lines displayed by looking (in order) at the following
sources:
v If the URL contains an ″&Count″ argument, use that number.
v If there is no ″&Count″ argument, look at the number specified in the Embedded View Properties box.
v If no number is specified in the Embedded View Properties box, use the server-wide default for the
number of lines.

Designing a form as a view or navigator template


In Web applications, to create an association between a form and a view or navigator, you can assign a
reserved name to the form. Domino uses the form as a template when users open the view or navigator.
This can be a good way to create a standard display for views and navigators in your site.

Use the following reserved form names to create an association between a form and a view or navigator.

Note that Domino requires an embedded view or the $$ViewBody field on the form, but ignores the
value.

Form name Design element required and description


$$ViewTemplate for viewname Embedded view or $$ViewBody field. Associates the form with a specific view.
The form name includes viewname, which is the alias for the view or when no
alias exists, the name of the view.
$$NavigatorTemplate for Embedded navigator or $$NavigatorBody field.
navigatorname
Associates the form with a specific navigator. The form name includes
navigatorname, which is the navigator name. For example, the form named
″$$NavigatorTemplate for World Map″ associates the form with the World Map
navigator.

Domino ignores create and read access lists on the form.

Chapter 8. Designing views 199


Form name Design element required and description
$$ViewTemplateDefault Embedded view or $$ViewBody field.

Makes this form the template for all Web views that aren’t associated with
another form.
$$NavigatorTemplateDefault Embedded navigator or $$NavigatorBody field.

Makes this form the template for all Web navigators that aren’t associated with
another form.

Using HTML formatting for views and columns


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

The following formula inserts the graphic new.gif if the document was created within the last five days;
otherwise, no graphic is displayed.
@IF (@NOW > @ADJUST(@CREATED; 0; 0; 5; 0; 0; 0); "";"
[<img src=/gifs/new.gif border=0>]")

Displaying a view as an applet in Web applications


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

200 Application Development with Domino Designer 7


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

To display a view applet in a Web application


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

To display an embedded view applet in a Web application


You can enable an embedded view as an applet independently of the element it is embedded in.
1. Open a form or page.
2. Place the cursor where you want the embedded view to display.
3. Choose Create - Embedded element - View and select the view you want to embed.
4. Choose Element - View Properties to open the properties box.
5. Click the Info tab. In the Web Access field, specify whether this view should display as an applet by
choosing one of the following:
″Using Java Applet″ indicates that the view applet is used in this embedded view regardless of the
view’s setting.
″Using HTML″indicates that the view applet is not used regardless of the view’s setting.
″Using View’s display property″ indicates the view’s settings are used for this embedded view.

Font support in the view applet


The view applet provides limited support for fonts. Since current versions of the Java Developer’s Kit
(prior to SDK 1.2) provide very limited support for text fonts, mapping between the Designer font set
and the font set supported by a specific Web browser is constrained by the SDK supported by a browser.
This can sometimes produce inconsistent results across different Web browsers. For best results use one of
the following font faces: Courier, Helvetica, or Times Roman.

Note: At this time, the view applet does not support DBCS.

To program a view applet


Use these @commands to program a view applet.

@command Description
ViewCollapse Collapses the selected document
ViewExpand Expands the selected document
ViewCollapseAll Collapses all documents
ViewExpandAll Expands all documents
ViewRefreshFields Refreshes view

Upon refresh, the view applet does not delete documents marked for deletion.
MoveToTrash Causes currently selected documents to be marked for deletion

202 Application Development with Domino Designer 7


@command Description
EmptyTrash Deletes documents that are marked for delete
Folder Moves or copies the selected documents to a folder
RemoveFromFolder Removes the selected document from the current folder

Allowing users to select view documents on the Web


When you are deciding how to display a view on the Web, you have several options. You can display it
as a view applet, render the view in HTML, or embed the view on a page or form. You can also allow
users to select documents in a view and then program action buttons to process the selected documents.
1. Open a view in Designer.
2. Select Design - View properties and click the Advanced tab.
3. Select the option ″For Web Access: Allow selection of documents.″
4. Save the view.
5. To see how the view displays on the Web, choose Design - Preview in Web browser and select a Web
browser from the list.
The view displays with a check box to the left of each document.
For information on adding action buttons to views, see the chapter ″Automation in Applications.″

Opening a view with a particular frameset on the Web


The Launch tab of the View Properties box lets you specify the frameset and frame that a view or view
applet should display in when it is launched on the Web.

You can also specify target frames for a document that a user selects or opens from a view or view
applet.

For views, you set this property with the ″Target Frame (double click)″ and ″Target Frame (single click)″
events in the Programmer’s pane.

For embedded views, you set the target frame property on the Info tab of the Embedded View Properties
box. The target frame specifies where the document is displayed when a user selects a document with a
single click or with the arrow keys, or with a double click.

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

Hiding a view from Notes users


v 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 don’t have access to
Notes menus.
v Select the view name in the design 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.
v Give the view a name and surround it with parentheses -- for example, (All).

Hiding a view from Web users


v Open the design toolbox, click the view name in the right pane, and choose Design - Design Properties.
Select ″Hide design element from Web clients.″

Chapter 8. Designing views 203


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.
v Give the view a name and surround it with parentheses -- for example, (All).

Showing a view only to users of older Notes releases


If you have a view tailored to users of older Notes releases, you can hide the view from anyone using
Lotus Notes Release 4.0 or later.
1. Open the Designer and click the view name.
2. Choose Design - Design Properties.
3. Click the Design tab and select ″Do not show this design element in menus of Notes R4 or later
clients.″

Refreshing view indexes


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

You can either create a full-text index for a database or allow users create a full-text index. If you want to
maintain control over creating an index, choose the option ″Restrict initial index build to designer or
manager.″

Refresh time options


To determine when to refresh an individual view, select a ″Refresh index″ option from the Advanced tab
of the View Properties box.
v Auto, after first use
Updates the view every time a user opens a view after the first time.
v Automatic
Updates the view whether or not users ever open the database. With this option, views open more
quickly.
v Manual
Relies on the user to refresh the view. This option is useful for large databases that don’t need to stay
uptodate. With this option, views open very quickly. Users just press F9 to refresh the view.
v 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, but 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 on the Options tab of the View Properties box determine how users see the
changes in a view. The choices are:
v Display indicator
Does not show view changes automatically. Instead, the refresh icon appears in the view and users
must click the icon to see any changes.

204 Application Development with Domino Designer 7


v Refresh display
Refreshes the display automatically before showing the view to users.
v 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.
v Refresh display from bottom row
Updates the view from the bottom up. This is useful in a chronological display where users are likely
to look for changes at the bottom of the view first.

Discard index options


To delete indexes automatically for a particular view and save disk space, specify a ″Discard index″
option from the Advanced tab of the View Properties box. (Note that 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.
v 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.
v If inactive for n days
Deletes a view index if the view hasn’t been used in a specified number of days. Domino rebuilds the
view index the next time a user opens the database. (This option doesn’t affect local databases.) Choose
this option for databases that users infrequently or unpredictably need.
v If inactive for 45 days
Preserves the view index and appends updates to the existing index unless the view is inactive for 45
days, in which case the index is discarded. Because this option takes up more disk space than the other
options, use this only for views that users frequently need, so they don’t have to wait for a new view
index to be created when they open the database.

When the view index is deleted


The Updall (Update All) server task, which runs by default on each server at 2 AM, deletes the view
index. Domino deletes the index the first time Updall runs after the index becomes eligible for deletion.
For example, if you select ″After each use″ and the view is used at 10 AM Tuesday, the index is not
actually discarded until 2 AM Wednesday.

If you choose to delete the index after one day, Domino waits until the index is at least one day (24
hours) old before deleting it. If the view is used at 10 AM Tuesday, it is only 16 hours old at 2 AM
Wednesday when Updall runs, so it is not deleted until the next time Updall runs at 2 AM Thursday.

For more information, see Administering the Domino System.

Adding a trash folder to an application


Many applications benefit from a trash folder that users can drag documents into. The topics are moved
into the trash folder and marked for deletion. In a Notes view, the documents remain in the Trash folder
until the user either presses F9 to refresh the view, or until the user closes the database and confirms the
deletion. If the user does not want to delete the documents, they remain in the trash folder marked for
deletion. The user can drag documents back into another view and remove the deletion mark. For an
example of a trash folder in an application, see the Lotus Domino Designer mail template.

Chapter 8. Designing views 205


To add a trash folder to an application, create a new folder and assign it the name ($trash). You then
need to write code for the folder events to handle the document deletions. For an example of how to
program the events for the $Trash folder, see the Notes Release 6 mail template (mail6.ntf).

Example of programming a $Trash file

The following examples are taken from the $Trash folder in the Notes Release 6 mail file:

Events

In the QueryRecalc event, the formula is:

@Command([MoveToTrash])

The Restore action uses the following code:


@Command([MoveToTrash]) {for Web}
@Command([ToolsRunMacro];"(Restore Document)") {for Client}

The agent for the restore action uses the following code:
@Command([EditRestoreDocument]);
@All
Delete
@Command([MoveToTrash]) {for Web}
Empty Trash
@Command([EmptyTrash]) {for Web & Client}

Trash folders in the view applet


If you display a trash folder as a view applet in a Web application, documents marked for deletion in a
Notes client are also marked for deletion in the view applet. But refreshing the view in a browser by
pressing F5 does not delete the documents from the trash folder unless you create an action to empty the
trash. For an example of this, see the Discussion template (discsw6.ntf).

Documents marked for deletion in the view applet will appear as marked for deletion in the Notes client
after you close and reopen the database in the Notes client.

Adding a view for soft deletions


In some databases, selecting a document and choosing Edit - Delete permanently deletes the document
from a database. In other databases, such as the Notes mail database, choosing Edit - Delete moves the
document into a Trash folder and stores it in a state of ″soft deletion.″ This state makes it possible for a
user to restore a document deleted in error. You can turn on soft deletions for a database and control how
long to retain soft deletions in a database before actually deleting the documents.

To turn on soft deletions for a database


1. Select the database in the Bookmark pane and choose Edit - Properties.
2. On the Advanced tab of the Database properties box, check ″Allow soft deletions.″
3. Set a value for ″Soft delete expire time in hours.″ The default value is 48 hours. After that amount of
time elapses, soft deletions are permanently removed from the database.

Displaying and restoring soft-deleted documents


Documents in the ’soft delete’ state do not display in typical views and folders. Instead, you must create
a shared view to contain and display documents in the soft deletion state. In this view, you can provide

206 Application Development with Domino Designer 7


the user with an action programmed to un-delete documents and restore them to the database. In the
Notes client, you can program the action with the formula @UndeleteDocument. In the Notes client, the
″Remove from Trash″ action in the Trash folder restores deleted mail messages.

A user can permanently delete documents from the Trash folder by selecting one or more documents and
choosing Edit - Delete or by pressing the DEL key. You could also provide an action that uses the
@HardDeleteDocument command to permanently remove documents from the Trash folder. For an
example of this, see the ″Empty Trash″ action in the Trash folder.

Form more information on the @UndeleteDocument and @HardDeleteDocument commands, see the Lotus
Domino Programming Guide.

DB2 query views


Like other types of Notes views, query views are design elements that are part of Notes applications.
However, a query view uses an SQL query to populate its data, instead of using a view formula that
selects notes from a Notes database.

Query views are dynamic. The query runs as a result of a view open or view rebuild event, and is
recalculated each time the view is opened or refreshed. You can also re-execute a query view with
different SQL queries to quickly access specific notes. This is in contrast to regular Notes views, which
need to be rebuilt by using the Indexer tasks UPDATE and UPDALL.

Because they are not persistent, query views do not occupy space in a Notes database.

Query views and federated data


Query views can be built to view any data that is visible to a DB2 database, either because the data is
contained in that database or because it is available to that database through DB2 federation. Federated
data is any data stored in a database other than a Notes database. For example, any data in existing DB2
tables or databases is considered federated data. You can choose to create query views that show Notes
data only, federated data only, or a combination of Notes and federated data.

Once a query view has been created, you can open individual records in the view to edit Notes data
contained in that record. However, you cannot open a record of federated data from the query view, or
make changes to one - you can only view federated data in the query view itself.

You can also order or sort a query view by specifying the sort order in the SQL query. However, the
ORDER BY clause only affects the view ordering if a #noteID column is not returned by the query.
Otherwise, by default, the view is sorted by Note ID. In any case, a Notes column sort overrides a DB2
sort.

Note: If a #noteID column used in the query SELECT statement is part of a table outside of the schema
associated with your DB2 enabled Notes database, it is considered DB2 data, not Notes data, as it does
not belong to the current DB2 enabled Notes database. Therefore, you may not be able to open the
resulting note, or you may open a random note or a design document instead.

You need to be aware of the following when creating query views:


v If you want to create a query view based on data in a DB2 enabled Notes database, you must first
have defined and populated a DB2 access view (DAV) for that database.
For more information on DAVs, see the chapter ″Working with DB2 Enabled Notes Databases.″
v Query views for federated data only do not require the use of DAVs. Therefore, Domino servers that
do not have DB2 Access for Lotus Domino installed can still be used to create query views for
federated data.

Chapter 8. Designing views 207


v If the query is based on federated, or non-Domino data, you cannot perform a Note Open of the Notes
view, as the view data does not correspond to data in a note.
v If the query view references Domino data through a DB2 Access View and selects the noteID from the
DAV, you can open the note.
v A query can be composed dynamically in the Notes client application by using the @prompt.

Using complex SQL queries in query views


You can use SQL to create complex queries that incorporate data from multiple DB2 tables and views in
one Notes query view. For example, a query view can join data from multiple DB2 tables/views;
therefore, an application designer can join data from two DB2 enabled Notes databases indirectly by
joining two separate DAVs.

Specifically, you can create a SELECT statement with the following clauses:
v Group by
v Having
v Join
v Union

CAUTION:
Query view functionality is designed so that you cannot build an SQL statement that does not
produce a result set. This is a security measure against inadvertent record deletion or change.

For specific information about SQL and creating SQL queries, see the SQL documentation specific to your
operating system.

Prerequisites for working with Notes databases that reside in DB2


In order to work with DB2 enabled Notes databases, your Domino administrator should have set up your
environment as follows:
v The DB2 Access server should be installed. This functionality enforces Domino database security (such
as ACLs and reader lists) for DB2 enabled Notes data. If DB2 Access for Lotus Domino is not installed
properly, some DB2 Designer functions will not be available.
v In order to run any query views, Notes data or federated data, You need a DB2 OS account name in
addition to your Notes user ID. These IDs must be linked in the Domino Directory via a DB2 account
name in your Person document (Administration tab). This maps your Notes ID to a DAV or QV. Have
the Domino Administrator use the ″Set DB2 user name″ tool in the IBM Domino Administrator Client
to set this field.
v The DB2 enabled Notes databases on which you will be working should be located on a DB2 Access
for Lotus Domino server.
v You should have Read access to the Domino catalog.
v To use Query Views with DB2 Federated Objects a new DB2 setting needs to be applied. Stop DB2, and
use the following path and command at the DB2 command prompt, and then restart DB2:
db2set -g DB2_ALLOW_SETAUTH_WITH_REMOTECONNECT=1

Creating a query view


1. In Domino Designer, open the database for which you want to create a query view.
2. Select Create - Design - View.
3. In the Create View dialog box, complete the following:

Field Action
View name Enter a name for this view

208 Application Development with Domino Designer 7


Field Action
View type Choose one of the following:
v Shared
v Shared, private on first use
v Shared, desktop private on first use
v Private
Select a location for the new If you want the view to appear at the top level in the list of views, do not select
view anything in this field. Otherwise, click the name of the view under which you
want the new view to appear.
Copy style from view Click this option and then:
v Click Blank if you do not want to copy another view’s style.
v Click the view whose style you want to copy.
Selection conditions Enable ″By SQL Query.″ Note that when this option is selected, the View types
are limited to the four options described above.

4. Click Query Window. Type your SQL query in the Edit SQL Query Formula dialog box. Make sure
the query is contained in quotes. For example:
"Select * from acmedb1.dav1"
where acmedb1 is the schema name of the DB2 table/view and dav1 is the name of the DAV that
contains the information you want to query.

Note: You can determine the schema name for your query (which is usually the same as the DB2
enabled Notes database filename) from DB2. Issue the query by selecting nsfschema from the Domino
Catalog, where the filepath = ’myfile.nsf’ (substitute the name of your Notes database for myfile.nsf.)
This file name is relative to the data directory. You need to have Read access to the catalog.
If you delete a DB2 enabled Notes database and create a new one with the same name, Domino will
reuse the same schema name if possible. However, if this is not possible, Domino may add a number
to the schema name. For example, if acme.nsf is deleted, and a new acme.nsf is created, the fully
qualified name of the DAV for the new database may change from acme.dav, for example, to
acme2.dav in DB2.
The new @function @DB2Schema can be used in a Query View SQL query to eliminate the guess
work of the actual DB2 schema name being used. See the topic @DB2Schema for more details on this
new function.
5. (Optional) Click Functions to obtain a list of functions to copy and paste into your query.
6. When you are finished, click Done.
7. Click Save and Customize. This opens the Designer View workpane. From here, you may continue to
customize your view.

Note: You can specify the maximum number of rows returned by an SQL query in View Properties.
However, there is also a row limit set by the administrator at the server level, so you should know this
limit prior to setting up any query views. As a designer, you can still set a row limit (in the View
Properties) less than that set at the server. The default limit is 500 rows.

Note: DB2 column names that have disallowed Notes field name characteristics (for example, columns
starting with a digit) are reported when the query is run. You will get the following Designer error
dialog:

″Field names must begin with a letter or the symbols _ and $ and . The rest of the name may contain the
letters A-Z, the digits 0-9, or the symbols _ and $ and . Spaces are not allowed.″

and the console will report something like:


05/02/2005 10:25:57 AM Invalid field name: 1

Chapter 8. Designing views 209


Additionally, the #UNID and #MODIFIED fields are not created. However, you will not get an invalid
field name warning in these cases.

If you want to use the values returned by any of these invalid columns, use the AS syntax in the Query
View’s SQL formula to rename them.

Managing query views


Once you have created a query view, you can insert new records in the view, or update or delete existing
ones, either through Notes or DB2.

Deleting records in a query view


You can delete records in a query view through Notes or in DB2. Refresh the view to update the Query
view display. However, it is important to remember that, when using Notes, you can only delete DAV
(Notes) data, not federated data.

Inserting/updating records in a query view


You can insert and update records in a query view through DB2 or Notes. However, because query views
are not dynamic, not all new documents or changes to existing documents display immediately. After
changes, rebuild the view using Shift-F9 to update the query view display.

Separating multi-value items


DAVs store text lists as a text string, and since Query Views read data directly from DB2, that is exactly
what is returned to a Query View. So, if you have a multi-value item that you want to separate out in
your QV, you must use the @Explode formula on the column that contains multiple values. In addition,
to ensure that the view is set up to handle many lines of data, on the View properties - Style tab, set the
Row Height and Shrink Rows to Content options to accommodate your data.

Updating query views


As query views can be built from a combination of Notes and federated data, how the query view is
updated depends on the nature of the data that was added or changed and how it was added.

Type of data Where updated How to refresh view


Notes data In Notes views or DAVs Changes are automatic; can also press F9
Federated In DB2 Rebuild query view by pressing Shift-F9

Setting the maximum number of rows in SQL queries


<Index ″SQL queries″ # ″setting maximum number of rows″ CrusaderID_6942_158738149>There are two
ways to specify the maximum allowable number of rows returned by an SQL query when using Query
Views in Domino Designer.
v On the Options tab of the View Properties box, select ″Maximum number of rows returned by a SQL
query″ and then specify the number of rows.
v Add the NOTES.INI variable DB2QueryViewRowLimit=value to the server’s NOTES.INI file. Set the
value to 0 for ″unlimited″ rows returned. Without this variable, the default is 500 rows.

Note: If the DB2QueryViewRowLimit variable is set at the server level, you can still limit the number of
rows to a smaller value. When both settings are in place, the smaller value is used.

For more information about NOTES.INI variables, see the NOTES.INI Appendix in the Domino
Administrator help.

210 Application Development with Domino Designer 7


@ functions for query views
@DB2Schema
When a Notes database is stored in DB2, the information contained in that database is contained in tables
that reside in a single DB2 grouping construct known as a schema. All references to those tables use the
table name preceded by the schema name, separated by a period (for example, ″schema.table″).

When an application developer wishes to use a SELECT statement in a query view, the name of the DB2
Access view (DAV) against which the query is being run must prefix the name of the DAV with the
schema name. Otherwise DB2 uses the Domino server’s DB2 user name as the schema in which to look
for the table. For example, if you run a query view with a SELECT statement against a table called dav1
and the designer has not used the schema name, DB2 will interpret the location of that table as residing
in <db2user>.dav1.

To avoid this, the application developer can look up the schema name from the catalog table using the
query:
SELECT nsfschema FROM domino.catalog WHERE filepath = ’<path to db2nsf>

However, having to do this each time a schema name is needed can be inconvenient.

Moreover, if the DB2 enabled Notes database is copied using File - Database - Copy, the new copy still
refers to the original database’s Domino tables. So any query views executed against these DB2 enabled
Notes databases would refer to the original table source.

A quicker and easier way to determine the schema name of a DB2 enabled Notes database is to use the @
function @DB2Schema, which, when used in a query formula, returns the name of the DB2 schema for a
specified DB2 enabled Notes database. In query views, @ functions may be incorporated in the
construction of the query formula, the evaluation of which results in a text string. All contexts in which
an @function may be used are supported. This includes view selection formulas and column formulas.

A sample query formula using @DB2Schema:


SELECT firstname, lastname FROM " + @DB2Schema( @DbName ) + ".dav1

Note: Use of @DB2Schema in, for example, column names causes @ERRORs if the user has replicated to
a native Notes database. Proper handling of errors via @IF, or other means, is recommended.

@IsDB2
The @IsDB2 function accepts a text argument representing the path, with the same rules that govern the
use of @DB2Schema. It returns either TRUE, meaning the DB2 enabled Notes database is stored in DB2,
or FALSE, meaning it is stored in native NSF format (or that the nature of source database cannot be
determined).

Chapter 8. Designing views 211


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

Outlines
Outlines, like imagemaps and navigators, provide a way for users to navigate through an application.
Unlike imagemaps or navigators, outlines let you maintain a navigational structure in only one place. As
your site or application changes, you make only one change in the source outline. Each navigational
structure that uses that outline source is dynamically updated.

You can create an outline that lets users navigate to the views and folders in your database, perform
actions, or link to other elements or URLs outside of your application. You can create an outline that
navigates through your entire application or site or through part of it.

Important features of outlines include:


v Outlines allow great flexibility of design. You can order how items appear and create different levels of
hierarchy, and you can use framesets to include multiple outlines that launch links in target frames.
v Outlines are customizable. You can control how the outline appears to users by changing text and
button styles and adding icons from your database’s shared resources.
v Outline entries are fully programmable. You can add logic that controls how outline entries are
rendered by the Notes client or Web browser.

Once you create the source outline, you embed it on a page or form to create an outline control, which
displays the outline to users as a site map or navigational structure. Users can click on the outline entries
to take them where you want them to go.

Overview of creating a navigator


To create a navigational structure using an outline, follow these steps:
1. Create a new blank or default outline.
2. Create outline entries for jumps or actions you want to present to the user.

213
3. Embed your outline on a form or page or in a rich-text field of a document.
4. Format the embedded outline.
5. (Optional) Include the embedded outline in a frameset.

Creating an outline
You can create a new outline or generate a default outline.

If you are using the outline to plan your application, you can create the outline entries prior to designing
the actual design elements. Begin by creating a new outline and then adding entries for each element you
plan to include in your application. You can include outline entries for any element that will be part of
your application or site, such as jumps to pages, documents, views, folders, Web pages, or other Domino
databases. Outline entries represent each piece or planned piece of your application or navigation
structure. Outline entries can also be clickable actions, or can be top-level categories that organize other
entries. You can also choose what icons display with the entry. You can organize your application into
units and create multiple outlines to represent the different portions of your application.

If you have already created all of your design elements or are working with a database created from a
template, you can begin by creating a default outline and customizing it.

Designing for accessibility


Use outlines instead of navigators to create applications that are accessible to assistive technologies like
screen readers. An outline lets you create an organizing structure for an application and gives you control
over how elements are displayed in a navigator pane. Outlines are programmable and customizable so
you can control the look of the outline while maintaining accessibility. If the outline will be used for Web
applications, do not select the option to display using the Java applet. Outlines displayed using the Java
applet are not accessible.

For more information on designing an application for maximum accessibility for people with disabilities,
see the topic ″Designing an application for maximum security″ in the chapter ″Planning an Application.″

To create a new outline


1. Click Shared Code - Outlines in the Design pane.
2. Click ″New Outline.″
3. Add outline entries for each design element, action, or link you want to include in the outline.
4. Save and name the outline. In the ″Save outline as″ box, type an outline name.
Specify an alias if you plan to embed the outline and there is a chance that the embedded outline
could be renamed. An alias allows you to change an outline name without rewriting formulas that
reference the embedded outline. An alias also remains the same if a database is translated or
modified. To specify an alias, type a vertical bar (|) followed by the alias name. For example,
OutlineName|OutlineAlias.

To create a default outline


The default outline creates outline entries for all the views and folders in the database. In addition, the
default outline contains placeholders called ″Other views,″ ″Other folders,″ ″Other private views,″ and
″Other private folders.″
1. Create a new outline.
2. Click ″Generate Default Outline.″

214 Application Development with Domino Designer 7


To add a new outline entry to an outline
1. Open or create an outline.
2. Click ″New Entry.″

Note: You can also cut and paste outline entries from other outlines.
3. In the Outline Entry Properties box, enter the label you want to appear in the outline, for example,
Home Page or Main View.
4. In the Outline Entry Properties box, type the popup text that you want to appear. Popup text appears
if the window is not wide enough to display the entire label and the user moves the mouse over the
outline entry.
5. (Optional) Specify an alias for the outline entry.
6. Specify a type for the element in the Content field. Types include:
v None - use this to create a top-level category for nesting entries.
v Action - choose this if you want the outline entry to perform an action such as open or create a
document. To enter an action, click the @ button, and enter a formula using the formula language.
v Link - such as to an anchor, document, view, or database link.
v Named element - such as a Page, Form, or View.
If you are creating a link to a named element that does not exist, Designer displays a prompt
saying that you will need to create the element later.
v URL.
7. (Optional) In the Value field, specify or paste in a value that corresponds to the Type that you have
chosen (for example, paste in a URL, if you have chosen Link; a formula, if you have chosen Action).
If you paste in a URL link, make sure the entire URL, including protocol, is available. For example
http://www.lotus.com.
8. (Optional) In the Frame field, specify the target frame where you want the action or link to be
displayed.
If you have not yet created a frameset, you can either enter the name you are planning to use in your
frameset or you can add this entry later, after you have created your frameset.

After you have created outline entries for the elements that you are including in your application, you
can reorder the elements or create a hierarchy that structures your content. The order of the outline
entries in the outline will be reflected in the embedded outline control.

To reorder elements in an outline


Create the order for the outline entries as you want them to appear to the user. To reorder the elements
after you create them, select one or more outline entries in the Design pane and drag to move them up or
down in the list.

To create a hierarchy between elements


Outline elements can have a hierarchy, that is, there can be top-level entries and subordinate entries. This
is especially useful, for example, if you want to create nested outline entries. To create a hierarchy
between elements, do one of the following:
v Select one or more outline entries and click ″Indent Entry″ (or press TAB) to indent the element one tab
stop to the right.
v Select one or more outline entries and click ″Outdent Entry″ (or press SHIFT+TAB) to outdent the
elements one tab stop to the left.

To delete an outline entry


1. Select an outline entry.
2. Press DEL or choose Edit - Delete.
Chapter 9. Designing navigation for an application 215
Embedding an outline
To use an outline as a navigational device, it must be embedded on a form, page, or rich text field of a
document. Whether you choose to embed your outline on a form, page, or document will depend on
how you want to use it. You can embed the outline on a form so that each document created from that
form includes the embedded outline. The outline then presents an easy way for users to navigate to other
views, create a new document, move to the next document, and so on. For example, in a Discussion
database, you can embed the outline on the Main Topic form. When a user creates a document with that
form, the outline appears on the document.

You might want outlines or outline entries to appear under certain circumstances or for only certain
kinds of users. Using the Programmer’s pane gives you greater flexibility in planning and designing your
outlines. For example, you can supply different outlines to Notes or Web browser users; or you can limit
access to outline entries based on users in different organizations such as sales or manufacturing.

The most common way to use an outline is to embed the outline on a page and use it as part of a
frameset. Embed the outline on multiple pages if you need to have several occurrences of the same
outline with different styles (for example, one outline with only text, another with graphical buttons).

If you want several navigational structures in one application you can do one of two things. You can
create one outline and embed it several times on different pages, or you can create several different
outlines and embed each on different pages.

To embed the outline on a page


1. Click Shared Code - Outlines in the Design pane.
2. Open the outline you wish to embed.
3. Click ″Use Outline″ on the action bar at the top of the Design pane. The embedded outline appears on
a new page with the default style applied to it.
4. If you do not want to display the same outline in all circumstances, write a formula in the
Programmer’s pane to display the appropriate outline.
5. Choose File - Save. As prompted, enter a name for the page on which the outline is embedded.

To embed the outline on a form, page, or document


1. Open or create the form, page, or document on which you want to embed the outline.
2. Position the cursor where you want the outline to appear. In a document you must be in a rich text
field.
3. Choose Create - Embedded Element - Outline.
4. From the dialog box, select the outline you want to embed. The dialog box lists all of the saved
outlines in the current database. You can also choose to embed an outline from a different database.
5. If you do not want to display the same outline in all circumstances, write a formula in the
Programmer’s pane to display the appropriate outline.
6. After you have embedded your outline, you can format it.

Outline, outline entry, and embedded outline properties


There are three sets of properties associated with outlines:

Property Description
Outline properties v Gives the outline a name and alias
v Makes the outline available to public access users
v Specifies that the outline be read only

216 Application Development with Domino Designer 7


Property Description
Outline entry properties v Assigns a label and alias to the outline entry
v Selects what the entry will do: Jump to a URL, link, or named
element, perform an action, or nothing
v Selects the link or enters a formula
v Enters the target frame for the action or link
v Selects the image
v Selects ″Does not keep selection focus ″
v Specifies that the outline entry be read only
v Selects hide options for the entry
Embedded outline properties v Formats the embedded outline’s look and structure

Selected outline properties


To make the outline available to public access users
This option must be enabled for the outline to be available to public access users - users with no access to
the database, but who have the privilege to read/write public documents. (Public access users will be
able to open the database to views enabled for public access and to read/write documents enabled for
public access.) If the designer wants the public access user to be able to use the outline for navigation, the
outline must be enabled for public access users. The page and frameset in which the outline appears
must also be enabled for public access users.

For more information about public access, see the topic ″Creating public access pages, forms, subforms,
outlines, views, agents, and style sheets″ in the chapter ″Security in an Application.″

To make the outline read only


If you select ″Read only,″ users cannot edit the outline in place.

Selected outline entry properties


Providing identifying information for an outline entry
1. Type the label that you want to appear in the outline entry.
2. (Optional) Type the popup text that you want to appear. Popup text appears if the window is not
wide enough to display the entire label and the user moves the mouse over the outline entry.
3. (Optional) Type an alias. An alias is useful if you refer to an outline entry in a formula.

Providing content for an outline entry


When you create an outline entry, you must provide content as follows.
1. In the Type field, choose one of the following ways to provide content for the outline entry:
v Action
Specify an action to provide an automated task.
For more information on actions, see the topic ″Actions″ in the chapter ″Adding Automation to an
Applications.″
v Link
Link requires that you paste a link that you’ve already copied to the Clipboard. Click the Paste icon
to paste one of the following kinds of links: View, Document, Anchor, or a database link.
For more information on links, see the topic ″Creating links″ in the chapter ″Designing Pages.″
v Named Element

Chapter 9. Designing navigation for an application 217


A named element is a design element that you have already created and named. A named element
can be a page, form, frameset, view, folder, or navigator.
v URL
To put a Web page into an outline entry, choose URL.
2. In the Value field, type a value for the element type you have chosen. For example, if you already
created a page named PAGE1, type PAGE1 in the Value field. If you chose a URL, type the full URL
specification (for example, http://www.lotus.com). You can also paste a URL or use a formula that
evaluates to a URL. Alternately, you can click one of the following:
v Use the folder icon to select a design element from a list in the Locate Object dialog box.
v Use the formula icon (@) to specify a formula that evaluates to a name. The formula resolves to the
name of an element; using a formula allows you to dynamically specify the outline entry source
(for example, whether the named element links to a page or a view).
v Use the paste icon to paste an element which you previously copied to the Clipboard.
3. (Optional) In the Frame field, type the target frame for the outline entry source.

To add an image to the entry


You can display an image with any outline entry. By default, outline entries for views display the view
icon, and outline entries for folders display the folder icon. You can display these icons, hide the icons, or
choose one of your own.

To add an image to appear next to your entry:


1. Select an outline entry and choose Design - Outline Entry Properties.
2. On the Outline Entry Info tab, do one of the following
v Click the folder icon in the Image section and select the shared image resource for your graphic.
v Click the @ button to use a formula to control the display of the image.
v Select ″Do not display an image.″

Does not keep selection focus


After a user clicks on the entry, the entry will not remain selected. The previously selected entry will
retain the focus.

Read only
If you select ″Read only,″ users cannot edit the outline in place.

To hide an entry
You may want certain entries to show up only under certain circumstances. For example, you can
program an entry to be hidden when viewed with a Web browser. To hide outline entries:
1. In the Outline Entry Properties box, click the Hide tab.
2. Select an option for hiding the entry or enter a formula in the formula box.

Selected embedded outline properties


An embedded outline has several areas you can format. Using the Embedded Outline Properties box, you
can set up the display of the outline, including images in the background area and a hierarchy style for
entries in the title, top-level, and sub-level area.

218 Application Development with Domino Designer 7


There are two different style properties that control how the embedded outline appears to the user: type
and title.

The first, Type, determines whether the outline shows the hierarchy of the outline entries. The hierarchy
is set up when you outdent and indent outline entries. If you select Tree style for type, then all of the
outline entries that have indented entries below them will show up as expandable sections. You can
choose to have green triangles (or twisties) display next to expandable outline entries, or users can click
on the top-level entry to expand it. In a Tree style outline, all top-level entries show at all times. Users
expand and collapse entries as necessary.

Tree style outline with twisties turned on:

Chapter 9. Designing navigation for an application 219


Tree style with simple title:

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

220 Application Development with Domino Designer 7


Initial display for flat style outline:

After clicking Phone Book entry:

To format an embedded outline


1. Open the form or page on which the outline is embedded.
2. Select the outline.
3. Choose Element - Outline Properties. The Embedded Outline Properties box appears for you to set the
overall display of the embedded outline.
Info tab:
v Type - Tree or Flat. This setting allows you to decide whether to show the hierarchy of the Outline
or not. Tree style shows all of the outline entries in the hierarchy, while Flat shows only one level at
a time. Use the Flat style selection in conjunction with the Title style setting.
If you choose Flat Style, you have the option of displaying the outline vertically or horizontally.
Display horizontally displays entries to fit the window across instead of down.
v Title style - Hide or Simple. Simple style lets users navigate back up to prior levels by displaying
the parent of the current level in an outline. Hide style does not display any hierarchy, so once
users go down a level in the outline they cannot navigate back up.
v Target frame - Specify the frame where you want the source (link, named element, or URL)
displayed.
v Twisties (Tree style only)
Show twisties - Select to display a triangle that users click to see outline entries.

Chapter 9. Designing navigation for an application 221


OS style - Select if you want the outline to appear in a structure similar to the Design pane in
Domino Designer. Instead of twisties, the user clicks a plus sign (+) to expand and a minus sign (-)
to collapse. This setting is supported on Windows platforms.
Image - Specify a custom twistie image instead of the triangle. Click the folder icon to select a
shared image resource.
Optionally, click the @ button to use a formula to control the image display.
v Columns (Flat Vertical style only)
Show as multiple columns - If you select this setting, the entries at any level automatically display
in columns (instead of using scroll bars) when the outline is longer than the allotted height. For
example, an outline that has entries that would normally require a height of three inches to display
would wrap into columns if the outline had a fixed height of one inch. However, if the outline
height is set to ″Fit to content,″ columns do not automatically appear because the outline height
increases to the height it needs.
Column width - Specify the width of the columns in inches.
v Root entry - Specify a root by using the parent entry label or the alias of the parent entry. (For
backwards compatibility with Lotus Domino Designer R5, you should specify the alias.) When you
specify a root entry, the children of the specified entry only are displayed. One use of this field is to
restrict access to elements in your site or database.
If the specified entry does not have any children, then nothing will display in the outline. If you
want to give users a way to navigate back up the hierarchy from the root entry’s children, enable
Simple as the Title style for either a Tree or Flat outline. If you want to limit users’ access to those
children entries only, set the root, and don’t enable a Title style.
v Outline size
Width
To specify the width of an embedded outline as a percentage of the parent window, choose Fit to
window (%).
To specify the width in inches of an embedded outline, choose Fixed (Size).
To allow automatic sizing of an outline based on its content -- for example, the number of entries
and whether or not the entries are expanded or collapsed -- choose Fit to content.
To specify the width as approximately the specified number of characters based on the average
character width of the specified font, choose Fixed (Chars).
Height
To specify the height in inches of an embedded outline, choose Fixed (height).
To allow automatic sizing of an outline based on its content -- for example, the number of entries
and whether or not the entries are expanded or collapsed -- choose Fit to content.
To allow automatic sizing of the height of an outline based on the size of the window that the
outline is displayed in regardless of its content, choose Fit to window.
Show scroll bar
To display a scroll bar if the embedded outline entries do not fit on the screen, select ″Show scroll
bar.″
v Web access - Select HTML or a Java applet to display an embedded outline to Web users.
v Special
Show folder unread information - If you select this option, folder names in the outline become
bolded when there is new or changed information; the unread count follows the folder name. For
example: Infobox (8). Note that this option works only on Lotus Notes Domino Release 6 or later.
Font tab
Select either Top-level font or Sub-level font to format the font of the outline entries. If Title style is
set to Simple, select the Title Font. You can also select font colors for:
v Normal state of entries

222 Application Development with Domino Designer 7


v Selected (when the entry is selected)
v Moused (when the mouse passes over the entry)
Background tab
For each of the areas on the embedded Outline, you can specify color or image backgrounds. You can
set mouse-over and selection colors. Images can be tiled in various ways, such as top to bottom, or
left to right, or positioned under the text, for button effects. Images must be shared image resources
for the database.
Layout tab
Set the positioning for the title-level (if Simple title is enabled), top-level, or the subsequent levels of:
v The entire outline entry
Height - height of each entry. (This setting represents the width of each entry in a flat horizontal
outline.)
Vertical offset - aligns the outline entries relative to the top edge of the embedded outline or
previous outline entry. If you want to customize the spacing between outline entries, use this
setting.
Horizontal offset - aligns the outline entries relative to the left edge of the embedded outline, for
title or top-level entries. Sub-level offset is relative to parent entry’s left edge.
v The label text of the outline entry
Alignment - within the outline entry.
Vertical offset - relative to the top or bottom edge of the outline entry, depending on alignment;
ignored for a middle vertical alignment.
Horizontal offset - relative to the left or right edge of the outline entry, depending on alignment;
ignored for a center horizontal alignment.
v The outline entry image
Alignment - within the outline entry.
Vertical offset - relative to the top or bottom edge of the embedded outline entry, depending on
alignment; ignored for a middle vertical alignment.
Horizontal offset -- relative to the left or right edge of the outline entry, depending on alignment;
ignored for a center horizontal alignment.
Border tab
Set a border style, effect, and thickness.
For more information on borders, see the topic ″Setting a border style, effect, and thickness″ in the
Lotus Notes Help.

Using the outline applet in Web applications


When you are designing a Web application, you have two options for defining how an embedded outline
displays in a browser:
v Define the embedded outline as HTML. This is the default behavior.
v Define the embedded outline as an applet.

The outline applet lets Web users work with outlines embedded in a page or form. With the outline
applet, Web browser users can:
v See mouse-over distinctions for items in the outline, including change of color to indicate a selected
item
v See background images

To enable the outline applet


1. Embed an outline in a page or form, or select an existing embedded outline.
2. Choose Element - Outline Properties.

Chapter 9. Designing navigation for an application 223


3. On the Info tab, select ″Web Access: Using Java Applet.″

Displaying the outline in a frameset


To add structure to your Web site or Notes database, after you have formatted the outline you can insert
it into a frameset.
1. Either create a new frameset or open an existing frameset.
2. Right-click on the frame in which you want the outline to appear and select the Frame Properties box.
3. In the Type field, select Named Element.
4. Select Page or Form. Enter a value by either clicking the Folder icon and selecting it from the list box
or typing the name of the page or form containing the outline.
5. (Optional) Click the formula icon (@) to enter a formula that evaluates to the named element.
6. (Optional) Enter the name of the target frame the links should appear in when a user clicks on an
outline entry.
For more information on framesets, see the chapter ″Designing Framesets.″

Navigators
Navigators are objects and graphics that include programmed areas that direct users to specific parts of a
database. They let users find documents or take actions without having to open views. If you are
designing a navigator for the Web, consider either embedding a navigator or importing a navigator into a
form, subform, page, or document.

Navigators usually include hotspots; that is, programmed areas that users click to execute an action. A
hotspot can be text, graphics, or a combination of both.

If you use navigators in an application, you usually want the navigator to display automatically when the
application opens.

To use a navigator in a Web application, you must select ″Web browser compatible″ as a navigator
property. With this setting on, Domino converts a navigator to an HTML imagemap. Navigators on the
Web always display as full-screen imagemaps. To control the size and display of a navigator on the Web,
you can embed a navigator in a form.

If your navigator inherits its design from a template, do not make any changes to the design of your
navigator, since any changes you make will be overwritten by the template.

Designing for accessibility


Navigators provide a graphical display of folders, views and design elements to make it easier for most
users to find information. However, you cannot access a navigator without a mouse, and the graphics are
inaccessible to assistive technologies like screen readers. To make navigators accessible to someone using
a keyboard or a screen reader, place all navigator actions on the Actions menu.

Outlines, navigation tools which provide the functional equivalent to navigators, are accessible and easier
to maintain than navigators. Whenever possible, use outlines in place of navigators to provide custom
navigation for your application.

For more information on designing an application for maximum accessibility, see the topic ″Designing an
application for maximum accessibility for people with disabilities″ in the chapter ″Planning an
Application.″

Navigator objects
You create a navigator by combining navigator objects and adding actions to objects. Navigator objects
include graphic backgrounds, hotspot rectangles, hotspot polygons, hotspot circles, graphic buttons,

224 Application Development with Domino Designer 7


buttons, text, rectangles, rounded rectangles, ellipses, polygons, and polylines. To create navigator objects,
you can import or paste objects from another application or you can use the drawing tools Designer
supplies.

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

Navigator actions
You can add actions to all navigator objects except those pasted or imported as graphic backgrounds.

Designer provides the following simple actions that you can attach to navigator objects:
v Open another navigator.
v Open a view or folder.
v Serve as an alias for a folder.
Click the object to display the contents of the designated folder in the view pane.
v Open a database, view, or document link.
v Open a URL.

To create more complex flexible actions use @function formulas or a LotusScript program. LotusScript
programs can perform tasks that aren’t possible with @function formulas. For example, manipulating a
database ACL.

For more information on writing formulas and scripts for buttons and hotspots, see the Domino Designer
Programming Guide.

Creating a navigator
If you can’t copy and paste a navigator that is similar to the one you need, create a new navigator.
1. Select Other - Navigators in the Design pane.
2. Click ″New Navigator.″
3. Choose Design - Navigator Properties.
4. Give the navigator a name that describes its use.
5. To use the navigator in a Web application, select ″Web browser compatible.″
6. (Optional) Choose an initial view or folder to open along with the navigator.
7. (Optional) Select ″Auto adjust panes at runtime″ so that users won’t have to manually resize a
navigator that doesn’t fit a window.
8. Click the navigator window.
9. Use the Create menu or the SmartIcons bar to draw objects or paste objects from the clipboard.
10. Click each object and choose Design - Object Properties to assign a name and style.
11. In the Programmer’s pane, select a Run option and assign actions to each object. Run options specify
what happens when users click the object.
v Select Simple action to choose a predefined automation, such as Open a View.
v Select Formula to define an action using the formula language.
v Select Script to define an action using LotusScript.
12. Close and save the navigator.

To edit a navigator
1. Open the navigator in Designer.
2. Choose Design - Navigator Properties and make changes as needed.

Chapter 9. Designing navigation for an application 225


3. (Optional) To change any object, click on the object, select Design - Object Properties, and make
changes as needed.

Adding graphic objects to navigators


You can create graphic objects in another product, such as a drawing, charting, or mapping package, and
import or paste the objects into a navigator as a graphic background for the whole navigator or as a
button that you automate with an action. A navigator can have only one background graphic, but it can
have many buttons.

Designer includes a set of drawing tools, available on the SmartIcons bar or on the Create menu, that you
can use to create or enhance graphic components of a navigator. The drawing tools are displayed in the
SmartIcons bar when the navigator is in Designer.

Note that polylines do not work on the Web, even though they display on the Web.

Adding and enhancing graphics in a navigator


The following types of files can be pasted or imported into a navigator:

BMP (Bitmap)

GIF

JPEG

PCX

TIFF 5.0s

Note: Graphic backgrounds cannot be moved; graphic buttons can be moved.

To paste a graphic from another product


1. Create a new navigator, or open an existing navigator.
2. Choose one of the following:
v Create - Graphic Button to paste the graphic as a button on the navigator.
v Create - Graphic Background to paste the graphic as a background for the navigator.
3. If you are creating a Graphic Button, drag the graphic where you want the button to appear.

To import a graphic
1. Create a new navigator, or open an existing navigator.
2. Choose File - Import.
3. Select the file to import and click OK.
4. Click Graphic Button to import the graphic as a button, or click Graphic Background to import the
graphic as a background for the navigator.

To edit a graphic
Double-click a drawn object to edit its properties. For example, you can change colors or widths of lines
on drawn objects.

Use drawing tools available from the Create menu or the SmartIcons bar to enhance existing objects.

To edit an object that is under another object, click the overlying object and choose Design - Send to Back
and then select the object you want to edit. Hotspots are always on top and cannot be sent to the back.

226 Application Development with Domino Designer 7


To delete a navigator object
To delete a navigator object (such as a button, graphic button, or rectangle), select the object and choose
Edit - Delete.

To remove a graphic background, choose Design - Remove Graphic Background.

Tips for drawing new navigator objects


v To create several identical navigator objects quickly, hold the SHIFT key down while choosing Create.
Draw all the objects you need; choose Create - <shape name> to exit create mode.
v To draw a square or a circle, hold the SHIFT key down while dragging the shape.
v To move an object that isn’t locked into position, drag the object to a new location.
v 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.
v To line up objects at a grid mark, choose Design - Navigator Properties, click the Grid tab, and select
″Snap to grid.″ Choose a grid size (1 pixel is the most precise).
v To freeze an object at its current position and size, click the object, choose Design - Object Properties,
and select ″Lock size and position.″

Adding text to and highlighting navigator objects


You can add text to most objects, including buttons, rectangles, polygons, and so on. You cannot add text
to the following objects: polylines, hotspot rectangles, hotspot polygons, graphic buttons, and graphic
backgrounds. You can also highlight an object. When an object is highlighted, its appearance changes
when the cursor is over it or when it is clicked.
1. Create a new navigator, or open an existing navigator.
2. Click a navigator object.
3. Choose Design - Object Properties.
4. Click the Info tab. Enter text for the object in the Caption box..
5. Click the HiLite tab.
v Select ″Highlight when touched″ to show the highlighted style when the user’s cursor passes over
the object.
v Select ″Highlight when clicked″ to show the highlighted style when the user clicks the object. The
object remains highlighted until the user clicks another object.
6. (Optional) Change the highlight border width, highlight border color, and highlight background color.
7. (Optional) Click the Styles tab and do one of the following to define the unhighlighted style:
v Select a border width, border color, and background color.
v For a button, select a button face color, bevel width, and border color.
v Select ″Make Default″ to apply to all new objects of this type.
8. Close and save the navigator.

Tip: Choose Design - Preview in Notes or Design - Preview in Web Browser <browser> to select the
highlight settings.

Adding hotspots
A hotspot is a programmed area that you click to execute an action. Hotspots are always topmost on a
navigator -- you cannot send them to the back.

To automate a hotspot, attach an action to it. For example, if your navigator is a map, you can create
hotspots so that a user clicking on a region in the map views information about that region.

Chapter 9. Designing navigation for an application 227


To create a hotspot
1. Create a new navigator, or open an existing navigator.
2. Use the Create menu to add a hotspot. For example, Create - Hotspot Polygon. (Or select a hotspot
tool from the SmartIcons palette.)
3. Click on the navigator and drag to create the hotspot. The polygon tool allows you to create a line
segment each time you click. Double-click to complete the drawing and close the polygon hotspot.
4. (Optional) Double-click the hotspot to edit its properties.

Adding actions to navigators


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

Simple actions for navigators


You can use these simple actions for navigators.

Action: Open a view or folder


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

Action: Alias a folder


When users click an object that activates a folder, the folder activated by that object replaces the current
folder (if one is open). To return to the original folder, use View - Go To.

Action: Open another navigator


When users click this object, the current navigator (if there is one) is replaced by the new navigator. The
replacement navigator must be from the same database.

Action: Open a link


The action prompts you to paste a link to a document, view, or database. When a user clicks this type of
object, Designer presents the specified document, view, or database.

Action: Open URL


The action prompts you to specify a URL to open. Clicking the navigator object opens the URL.

Custom actions
You can use an @function formula or a LotusScript program to define a custom action. A navigator that
runs an @function formula allows you to create specialized actions that aren’t related to switching to a
view, a folder, a navigator, or a link.

To attach an action
1. Create a new navigator, or open an existing navigator.
2. Select a navigator object.
3. In the Programmer’s pane, click ″Run: Simple action(s).″
4. Select the simple action to run and supply any required information.
5. Close and save the navigator.

To attach a formula or script


1. Create a new navigator, or open an existing navigator.
2. Select the navigator object.
3. To add a formula, select ″Run: Formula″ in the Programmer’s pane. Then, type the formula and click
the green check mark to confirm it.

228 Application Development with Domino Designer 7


4. To add a script, select ″Run: LotusScript″ in the Programmer’s pane. Then, write the LotusScript
program.
5. Close and save the navigator.

For more information on writing formulas and scripts for buttons and hotspots, see the Domino Designer
Programming Guide.

Examples
This section includes examples of automating navigators.

Opening a view
A navigator that switches to another view gives users a graphical way to choose a view so they don’t
need to know the name of a view in the view pane. The Main Navigator in the Discussion template uses
objects to open these views: All Documents, By Category, and By Author.

Creating a navigator object that opens a navigator


A navigator object (such as a button) that switches to another navigator is a graphical way to guide users
through a series of decisions to reach the information they need.

This navigator displays a bar chart created in 1-2-3.

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

Chapter 9. Designing navigation for an application 229


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

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

Making a navigator object that runs a LotusScript program


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

Displaying a navigator when users open a database


You can set up a navigator to appear 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.
v To display the navigator in a navigation pane, select ″When opened in the Notes client: Open
designated Navigator.″
v To display the navigator in a full-screen window, select ″When opened in the Notes client: Open
designated Navigator in its own window.″ Note that the regular navigation, view, and preview
panes are not available from a full-screen navigator, but users can choose View - Go To and then
choose the view name to return to a specific view.
3. Select Standard Navigator in the Type of Navigator field.
4. Select the name of the navigator in the Name field.

Hiding navigators
Designer includes several ways to hide a navigator from users. There may be times when you want to
present one navigator to Notes users and another to Web browser users.

To hide a navigator from Notes users


Open a database in Designer and click Other - Navigators in the Design pane. Highlight a navigator
name in the Work pane and choose Design - Design Properties. Click the Design tab and select ″Hide
design element from Notes R4.6 or later clients.″

230 Application Development with Domino Designer 7


To hide a navigator from Web users
Open a database in Designer and click Other - Navigators in the Design pane. Highlight a navigator
name in the Work pane and choose Design - Design Properties. Click the Design tab and select ″Hide
design element from Web browsers.″

To hide a navigator from users of Notes Releases 4 and higher


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

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


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

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

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


1. Open a form, subform, or page in Designer or open a document in the Notes Edit mode.
2. Place the cursor where you want to embed an element.
3. Choose Create - Embedded Element - Navigator. The Insert Embedded Navigator dialog box appears.
4. Select a navigator to embed.
5. (Optional) If you don’t want to display the same navigator in all circumstances, click ″Choose a
Navigator based on a formula″ in the Insert Navigator dialog box. When you click OK to close the
dialog box, write a formula in the design pane to display the appropriate navigator.
6. (Optional) Click the embedded element and choose Element - Navigator Properties. The Embedded
Navigator Properties box appears. You can then change the alignment, style, or hide the element
under certain conditions.
7. Close and save the form, subform, page, or document.

To change the navigator, click the embedded navigator and choose another from the list in the
Programmer’s pane.

You can embed multiple navigators anywhere on a form, subform, page, or document, in tables, in
collapsed sections, and in design elements having a left, right, or center alignment. Avoid hiding
embedded navigators with the ″Hide design element from Web browsers″ option. Forms with hidden
navigators won’t display on the Web.

To delete an embedded navigator


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

Overriding an embedded navigator with a navigator template


A navigator template is a navigator that has the name $$NavigatorTemplate for <navigator name>. In a
Web application, Domino displays the navigator that was named in the form or page name in every
embedded navigator. To override this behavior, designate only one embedded navigator as the one to
reference the form name navigator or page name navigator and ignore its original value.

There is no equivalent procedure for $$NavigatorBody fields.


1. Select the embedded navigator and choose Element - Navigator Properties. The Embedded Navigator
Properties box appears.

Chapter 9. Designing navigation for an application 231


2. Click the Info tab and select ″Display navigator specified in form name when this form is used as a
Navigator Template.″

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


When you import a navigator into a form, subform, page, or document, a composite image of the
navigator is pasted in. The imported navigator actually becomes a picture object so that you edit it. The
navigator text boxes, graphic buttons, polygons, and other navigator objects are converted to imagemap
hotspots on the newly created picture object.

An advantage of importing a navigator is that formulas and LotusScript that were originally attached to
navigator objects become attached to the imagemap hotspots. Imported navigators, unlike navigators and
embedded navigators, allow you to make changes to the formulas and the LotusScript. An imported
navigator, unlike an embedded navigator, has no links to the original navigator.

Note that you can import only navigators that are Web-browser compatible. Select ″Web browser
compatible″ at the Info tab of the Navigator Properties box for the navigator you want to import.

When you import a navigator, navigator simple actions are converted to equivalent hotspots:

Navigator Simple Action Hotspot equivalent


Open another Navigator @Command([OpenNavigator];″NavigatorName″)
Open a View or Folder @Command([OpenView];″ViewOrFolderName″)
Alias a Folder @Command([OpenView];″FolderName″)
Open a Link Resource link of type ″link″
Open URL Resource link of type ″URL″

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


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

Testing navigators
To test a navigator while you design it, switch to Testing mode to see 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. You can preview in either Notes or a Browser to see how the
action actually performs.

To test a navigator, follow these steps.


1. Create a new navigator, or open an existing navigator.
2. Choose Design - Preview in Notes or Design - Preview in Web Browser <Web browser>.
3. Highlight and click each object to see if it works correctly.
4. If the test produces unexpected results, close the previewed item and use the Windows task bar to
return to Designer.

232 Application Development with Domino Designer 7


5. Correct the problems and run the test again.
6. When the test shows no problems, close and save the navigator.

Creating an imagemap
An imagemap is a graphic you enhance with programmable hotspots that perform some action when a
user clicks on them. Image maps are often used as navigational structures in an application. For example,
an imagemap of a plate of food might have hotspots users click to see recipes for the food pictured.
Unlike a navigator, which is an independent design element, an imagemap resides on a page or form, so
you can easily combine an imagemap with text and other page or form elements, and you can control the
display of an imagemap using a hide-when or computed-for-display formula. If you plan to create a site
map or navigator that combines several graphics with text and action buttons, create a navigator instead
of an imagemap.

An imagemap can be any graphic you can paste or import into a page or form, with the exception of
graphics in PI format. If you create an imagemap and then need to change the graphic, you can change
the graphic while keeping the hotspots intact.

To create an imagemap
1. Paste, create, or import a graphic or image resource on a page or form.
2. Select the graphic.
3. Choose Picture - Add Hotspot <hotspot shape>.
4. Click and drag to draw the hotspot on the graphic.

Note: To draw a polygon hotspot, click the points of the polygon, double-clicking to close the shape.
To draw a hotspot around the entire graphic, select Default Hotspot.
5. Do one of the following:
v Choose Picture - Hotspot properties. On the Hotspot Info tab of the Hotspot <shape> Properties box,
specify a link, named element link, or URL link. For information on linking, see the topic ″Creating
links″ in the chapter ″Designing Pages.″
v In the Script area of the Programmer’s pane, specify a simple action , formula, or LotusScript or
JavaScript routine to run when a user clicks the hotspot.
6. On the Advanced tab, add alternate text.
7. (Optional) Specify a target frame where the linked document will display when a user clicks the
hotspot.
8. (Optional) On the Advanced tab, specify the Imagemap tab order for the hotspot. The tab order
specifies the order in which hotspots are selected when a user presses the TAB key.

To move a hotspot
Once you create a hotspot you can move it as necessary. To move a hotspot, do one of the following:
v Click and drag the hotspot that you want to move.
v Select the hotspot and use the arrow keys to move one pixel at a time.

To delete a hotspot from an imagemap


1. Select the hotspot.
2. Choose Picture - Delete Selected Hotspot(s).

To copy an imagemap
You can copy an imagemap from another page, form, or document, and Designer will maintain all of the
hotspots from the original imagemap.

Chapter 9. Designing navigation for an application 233


1. Select an imagemap and copy it to the Clipboard.
2. Open the page or form where you want to place the imagemap and choose Edit - Paste.

To change the graphic for an imagemap


1. Select the current graphic.
2. Choose Picture - Replace picture.

234 Application Development with Domino Designer 7


Chapter 10. Adding automation to applications
Automation in an application speeds up repetitive tasks, handles workflow, updates information,
performs calculations, runs programs, and checks for errors.

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

To set up the tasks associated with these automated components, use the following:
v Simple actions
You can add automation to design elements without knowing a programming language. You can select
one or more simple actions from a list. Simple actions can’t be customized and are not supported in
Web applications.
v Formulas
You can write an @function formula that runs by itself or with a simple action. You cannot combine
LotusScript® in an @function formula. You can use some @functions in LotusScript using the
LotusScript Evaluate function.
v LotusScript
LotusScript is a complete scripting language that can support most application-wide tasks.
v JavaScript
Use JavaScript triggered in events (for example, onClick of a button or onLoad of a form) to interact
efficiently with the user for tasks such as form and field validation and simulating dialog boxes. Use
Common JavaScript to enter code that works on both the Notes client and the Web.
v Java
You can write Java programs or import Java files into agents.

Note: Lotus Domino Designer Release 6 and later supports code modules that are greater than 64K for
LotusScript, JavaScript, and Java.

235
Actions
You can create an unshared action in a view, folder, form, page, or subform to provide one-click shortcuts
for routine tasks in a view or document. Actions become part of a design element’s design and are not
stored with individual documents.

You can also create a shared action in a database that can be used in multiple views, folders, pages,
forms, and subforms. Shared actions are stored as shared resources in the database.

To build an action, you can use any of the following:


v Simple actions that you select from a list
v Formulas
v LotusScript
v JavaScript
v Common JavaScript

When to use actions


Because actions are available in a view or document, use them for any general-purpose task related to a
group of documents. For example, use actions:
v When Web browsers accessing the database need substitutes for Notes menu choices.
v To present a shortcut as a clickable button.
v When the automated task is relevant only to a subset of documents.
v When users need to see all the available choices in a row at the top of a document.
v When the automated task isn’t limited to a particular section of a form.
v If formulas are complex and you don’t want to save the formula with each document.

Examples of actions
v View actions -- Let users create, print, delete, or categorize documents.
v Form actions -- Process an approval; mail a document; or give Web users, who don’t have access to
Notes menus, a way to click to edit, save, or close documents.
v Simulate Notes menus for Web users.
v Automatically send documents to reviewers.
v Automatically process employee requests.

Notes on actions
Some views and forms in databases contain system actions, available either in the Actions menu, as
buttons, or both. You can’t change the ″System actions″ functionality, but you can customize their
appearance in the action bar. Open the view or form. Click Objects and the system actions are displayed
in the list.

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

236 Application Development with Domino Designer 7


v Button
Complete a programmed task, using simple actions, formulas, LotusScript, JavaScript when the button
is used in the Notes client. In addition, you can code the same button to run JavaScript when the
button is used in a Web browser.
v Formula pop-up
Complete a programmed task using only formulas, with the results displayed in the pop-up.
v Action hotspot
Complete a programmed task using simple actions, formulas, LotusScript, or JavaScript when the
action hotspot is used in the Notes Client. In addition, you can code the same action hotspot to run
JavaScript when the action hotspot is used in a Web browser.

When to use hotspots


Create a hotspot in a document when the hotspot is specific to the document. Create a hotspot in a form
when every document using that form needs the hotspot.

Examples of hotspots
v Use a document or database link to provide a cross-reference for more information that is stored in a
document in other database.
v Use a URL link to cross-reference a Web site for downloading software.
v Use a text pop-up to provide help information about what values to specify in a field.
v Use a button to submit a completed document for processing or add a database to a user’s workspace.

Agents
Agents are stand-alone programs that perform a specific task in one or more databases. Agents are the
most flexible type of automation because they:
v Can be run by users in the foreground or run automatically in the background as scheduled agents.
v Are not associated with a specific design element.
v Can be run on a specific server, on several servers, on workstations, or the Web.
v Can call other agents.
v Can consist of simple actions, formulas, LotusScript, or Java programs.
v Can be distributed easily because they can be replicated.
v Can be shared or private.
– A shared agent is created by one user and can be run by other users.
– A private agent (sometimes called a personal agent) is usually created and run by the same user. In
Lotus Notes, the private agent is not available on the Actions menu. In Domino Designer, anyone
with Designer level access or higher can see and run a private agent.

Because agents are so flexible and powerful, you might consider their characteristics first to decide the
type of agent you want to build, and then build it.

The Agent Manager supports all aspects of running and troubleshooting agents. The Agent Manager
checks security, manages agent scheduling, monitors events and starts the appropriate agents when their
associated events occur, records information in a log (the Agent Log), and performs database operations
to run the automated tasks associated with the agent. Although you don’t work directly with the Agent
Manager, you use its components for troubleshooting an agent.

When to use agents


Use agents for database-wide and domain-wide automated tasks and for complicated automated tasks.
You can use them to easily access, process, and manage data on other servers or in other databases.

Chapter 10. Adding automation to applications 237


See ″Agents to run before Web users open or save documents″ for an example.

Notes on agents
Some databases and templates have built-in agents. For example, the mail template has several built-in
agents that let users manage their messages and customize their mail databases.

To see the agents in a database, select the database and choose View - Agents.

Events
When users work in Domino design elements, Domino tracks their operations as events (for example,
opening a database, opening a view, opening a document). You can attach programming tasks to these
events.

To build a program for an event, you can use:


v Formulas
v Simple actions
v LotusScript
v JavaScript
v Common JavaScript (which works on both the Web and the Notes client)

When to use event programming


Use event programming to run tasks that users shouldn’t have to activate themselves and that are very
specific. Event programming is particularly useful when the timing of the program must be precise or the
tasks are associated with a particular design element.

For a table of events that can be automated, see Event Descriptions in the Domino Designer Programming
Guide.

Examples of event programming


v Error checking when a user completes a field or closes a document
v Recalculating fields when a user saves a document
v Prohibiting certain actions in a document
v Prompting for user input
v Displaying information when a user clicks a button

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

Database events
Database events pinpoint database-wide activities such as opening and closing a database or deleting and
undeleting documents.

Examples:
v PostOpen -- open a specific view to direct users to action items
v QueryDocumentDelete -- prevent users from deleting a particular document when the value of a status
field on an action item is ″Open.″
v PostDocumentDelete -- archive a deleted document.

238 Application Development with Domino Designer 7


v QueryClose -- prevent users from closing a database when there are still action items in the action item
view assigned to them.

View and folder events


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

Examples of view and folder events


v QueryOpen -- prevent users from opening a view in certain circumstances such as from opening a
″month end″ view before the twentieth day of the month.
v PostOpen -- create a new document or open an existing one.
v QueryRecalc -- inform users before a large view refreshes that it could take a while and ask them if
they really want to proceed.
v QueryPaste -- prevent users from pasting documents into the database.
v PostPaste -- change the value of StartDateTime and EndDateTime in the document when you paste an
appointment on a particular day and time slot.
v QueryClose -- prevent users from closing a view such as when there are still action items in the action
item view assigned to them.
v QueryAddToFolder -- lets you prevent someone from dragging a document from one folder or view to
another. For example, you can prevent documents from moving to the Done folder if their status is still
Open. Note that the trigger for this event is in the view or folder from which the document is moved.

In addition to the events available for all views, calendar views have specific events.

Examples of calendar view events


v RegionDoubleClick -- create a new document when users click an area in a calendar view.
v QueryDragDrop -- prevent someone from dropping an appointment on an inappropriate day or time,
such as a weekend day or a time that is after 5 PM.
v PostDragDrop -- change the value of StartDateTime and EndDateTime in the document after you drop
an appointment on a particular day and time slot.

Form events
Form events occur at the document level when users open or close a document. They are useful for
speeding up document display times because they execute only when a specific form event occurs, unlike
field recalculations that occur each time a document is saved, opened, or refreshed.

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

Field events
Field events capture users’ movements into or away from a field.

Chapter 10. Adding automation to applications 239


Examples
v Entering -- refresh hide-when formulas
v Exiting -- guide users to a certain field
v Exiting -- verify that users supplied valid information

Click events
The Click event occurs when users click actions or hotspots, or choose tasks from the Actions menu.
Other events for actions, buttons, and hotspots allow you to add programming to other events. After the
object is loaded, the ″initialize″ event is triggered and then the click event is triggered.

Examples
v Compose a new document
v Save a form
v Make a calculation

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

Creating a form, subform, page, or view action


You can create actions in forms, subforms, pages, views, or folders to provide one-click shortcuts for
routine tasks in a view or document. Actions become part of a design element’s design and are not stored
with individual documents. To create an action:
1. Open a form, subform, page, view, or folder.
2. Choose Create - Action - Action. The Actions Properties box appears.
Note that from the Create - Action menu you can also create an action with subactions or you can
insert system actions or insert shared actions.
3. On the Action Info tab, do one or more of the following:
v Enter a name for the action.
v Label name - If you want dynamic labeling of actions, you can enter a formula in the label field.
The dynamic label then appears as the name in the button or checkbox and on the action menu.
Note that dynamic labeling works only in Lotus Domino Designer 6 or later. Earlier versions of
Domino Designer use the name as the label.
v If applicable, specify a target frame (in the current frameset) to be the target of the action. For
example, if you create an action that opens a view, specify the name of the frame in which the view
should open.
v Select the display type for the action. You can choose Button, Checkbox, or Menu separator.
Checkbox lets you show the state of an item (checked or unchecked). If you choose Checkbox, you
can enter a Value in the Value field (for example, a formula that evalutes to true of false). You can
also highlight the Click event in the Objects list of the Programmer’s pane to enter a Click value. If
you want the action bar’s state (checkbox) to be reevaluated when a different document becomes
current, make sure to check the ″Evaluate actions for every document change″ option at the
Options tab of the Views Properties box. You can also use the @GetViewInfo function. For an
example of a checkbox action, see ″Displaying hidden text with a checkbox action.″
If you choose Menu separator, a menu separator appears and there is no action. You can also use
menu separators between subactions of an action drop-down list.
v Check ″Include action in Action bar″ to make the action available as an item in the action bar.
v If the action is a button action, you can also choose to have only the icon appear in the action
control bar.

240 Application Development with Domino Designer 7


v Check ″Right align action control″ to have the action control aligned on the opposite side of
whatever is set in the Action Bar Properties box. Note that it may not necessarily be right aligned.
For example, If you choose ″Buttons start at left″ in the Action Bar Properties box and ″Right align
action control″ in the Action Properties box, then the button appears on the right. However, if you
chose ″Buttons start at right″ in the Action Bar Properties box and ″Right align action control in the
Action Properties box, the button is actually aligned on the left, that is, on the opposite side of the
setting in the Action Bar Properties box.
v Check ″Include action in Action menu″ to make the action available as a menu item in the Actions
menu.
v Check ″Include in right mouse button menu″ to make the action available as a right mouse click
menu item for views. The action will be listed in a new section at the bottom of the right mouse
click menu. When the action is hidden on the Action menu, it will be hidden on the right mouse
click menu. If the action is a shared action, it will be visible on the right mouse click menu of all
views using that shared action.
v You can select an icon to appear on the action button. The icon will not appear on the right mouse
click menu. If you prefer a Notes graphic, select Notes and then click Image to select a graphic for
the icon from a set available in Notes.
If you prefer a customized graphic, select Custom. In the Image field, specify the name of an image
resource or click the folder icon to browse for an image resource. The image resource must reside in
the current database. You can specify the name of an image resource that does not yet exist.
Designer warns you that the image does not exist and that you must create it later. Click @ and
specify a formula (or set of formulas) to display an image programmatically.

Tip: If you do not specify a name or label for the action, Notes will use the graphic for the whole
button. You won’t be able to see the action in the action list, because there’s no name for it, but you
can click on the space at the end of the action list to access it.
4. (Optional) On the Action Hide When tab, specify when to hide the action.
5. (Optional) On the Advanced tab, specify how Notes workflow proceeds after the user activates the
action.
6. In the Info List of the Programmer’s pane, click Objects and select the action you just created.
7. To program the action to run one of the client or one of the Web program code types, choose either
Client or Web at the Run pull-down list.
Choose Client when the automated task will run in the Notes client. You can then select one of the
following Client code options:
v Simple actions
v Formula
v LotusScript
v JavaScript (runs only on the Notes client)
v Common JavaScript (runs on both the Notes client and the Web)
Choose Web when the automated task will run in a Web browser. You can then select one of the
following Web code options:
v JavaScript (runs only on the Web)
v Common JavaScript (runs on both the Notes client and the Web)
8. Save the form, subform, page, view, or folder.

To create an action with subaction


Creating actions with one of more subactions lets you create a hierarchical list of actions. You can also
drag and drop actions to create hierarchies. To create an action with subactions:
1. Open a form, subform, page, view, or folder.

Chapter 10. Adding automation to applications 241


2. Choose Create - Action - Action with Sub Action. A main action with an indented sub-action appears
in the Action pane. The Actions Properties box also appears.
3. Define the main action and the sub-action.
You can also drag and drop other actions so they are subactions of the main action.

To create system actions


When you create system actions, you are creating a predefined list of common view and form actions.
1. Open the form or view.
2. Choose Create - Action - System actions. The list of actions created appears in the Action pane. These
system actions include:
v Categorize
v Edit document
v Send document
v Forward
v Move to folder
v Remove from folder

Copying and deleting actions


To copy: select the action in the Action pane and choose Edit - Copy and Edit - Paste.

To delete: select the action in the Action pane and choose Edit - Delete.

To change properties: select the action in the Objects list and choose Design - Action Properties.

To change automation: select the action in the Objects list and edit the programming tasks in the right
pane.

Actions menu
The Actions menu is a context-sensitive list of any actions and agents available for a particular part of an
application, as well as some menu commands included with the Notes software. From an open view,
Notes users see only those actions associated with the view, plus any manually run agents. From an open
document, Notes users see the actions associated with the form used to create the document, plus any
manually run agents. Web users don’t see the Actions menu.

Calling an agent
You can use a form or view action to run an agent. Use the @Command([RunAgent]),
@Command([ToolsRunMacro]), or the OpenAgent URL command to call an agent.

Action bar
The action bar is a horizontal button bar that lies below the SmartIcons bar. If there are system actions or
actions you created to be displayed as buttons, users see the buttons when they open the view or create a
document using the form.

The Action Bar Properties box lets you set the style of the action bar and its buttons. You can also enable
the Domino action bar applet for Web users.
1. Choose Design - Action Bar. The Action Bar Properties box opens.
2. On the Action Bar Info tab, select one or more of the following:
v Alignment - lets you choose whether to have the action bar buttons align from the left or the right.

242 Application Development with Domino Designer 7


v Web Access - lets you use the Domino action bar applet so that the action bar displays better to
Web users.
- To enable the applet, select ″Using Java Applet.″ The applet lets Web users:
Scroll across the action bar, when needed.
For actions that have pull-down list selections for Notes client users, the action selections are
displayed as a second row of buttons when the user clicks the main action. The second row of
buttons is displayed at 75% the size of the main action buttons. Web users can view all the
selections and click one to select it.
- To disable the applet, select ″Using HTML.″

Note: If you want buttons to align from the right on the Web, you must choose ″Using Java
Applet.″
3. On the Action Bar Size tab, select one or more of the following:
v Bar height - choose one of the following:
- Default - automatically determines the appropriate height for the action bar.
- Exs - specify the size of the action bar in exs. An exs is equal to the size of the lower case of the
font that you have chosen. A height of three exs is equal to three times the size of the lower case
font you have chosen.
- Fixed - specify an absolute bar height in pixels.
v Font, Size, and Style - if you selected Exs, specify the font, the size of the font, and the style of the
font (for example, bold or italic) for the items in the Action Bar.
4. On the Action Bar Background tab, select one or more of the following:
v Color - specify a color for the background of the action bar.
v Image - you can also choose to use an image for the background. To use an image, click the folder
icon and select the name of a shared image resource that you have created and stored in the
database as a Resource, or click @ and specify a formula (or set of formulas). Note that using an
image may not be supported on the Web.
v Options - lets you choose how to present the background image. For example, you can center it, tile
it, repeat the image vertically, and so on.
5. On the Action Bar Border tab, select one or more of the following:
v Border style and color - choose the style and color of the action bar border. For example, you can
choose a solid line border or a border with a ridge or no border at all.
v Border effects - lets you choose to have a drop shadow border and set its width in pixels.
You can also set the thickness of the border (as well as the thickness of the outside and inside
border, if applicable).
6. On the Button Properties tab, select one or more of the following:
v Button Size - lets you set the height, the width, and the margin for all the buttons on the action bar.
If you choose Fixed size, you can specify the size in pixels.
If you choose default for the height, for the width, or for the margin, its size is automatically set.
Note that if you have images that are much taller than the font, you should not choose a default
height, but should specify a fixed height.
v Button Options:
- Display border - controls when the button border displays. You can choose to display the button
border On Mouse Over, Always, or Never.
- Align text - choose whether to have button text aligned center, left, or right.
- Internal margins - set the margins within the button in pixels.
- Always show drop-down - checking this causes the drop-down character (down caret) to display
inside the Action button. If this is not checked, the drop-down character displays only on mouse
over.

Chapter 10. Adding automation to applications 243


v Button Background - lets you either select a color for the button background or use an image for
the background. To use an image, click the folder icon and select the name of a shared image
resource that you have created and stored in the database as a Resource, or click @ and specify a
formula (or set of formulas). Note that using an image is not supported on the Web.
7. On the Button Font tab, select the font properties for the buttons on the action bar. You can set the
font, the size of the font, the color of font, and the font style.

Creating and inserting shared actions


Shared actions are stored in databases and can be found under the Shared Code heading in the Design
pane. Once you create a shared action, any other view, folder, form, subform, or page in the database can
access the shared action.

To create a shared action


1. Open the database where you want to store the shared action.
2. Click Shared Code in the Design pane.
3. Click Actions. A list of shared actions appears with information about each shared action.
This information lets you know whether the shared action appears in an action bar or in a menu,
whether a graphic is associated with the action, what the code type is (formula, simple action,
LotusScript, JavaScript, or Common JavaScript), and whether the action appears in Notes, on the
Web, or for mobile users.
Note that if the database is set up to be a multilingual database, shared actions can be grouped
under multiple sections called shared action notes. These shared action notes act like folders for
different languages.
4. To create a new shared action, click the New Shared Action button. (If you have shared action notes,
make sure you first select the shared action note under which you want the shared action to appear.)
The Actions Properties box appears.
5. On the Action Info tab:
v Enter a name for the shared action.
v Label name -If you want dynamic labeling of actions, enter a formula in the label field. The
dynamic label then appears as the name in the button or checkbox and on the action menu. Note
that dynamic labeling works only in Lotus Domino Designer 6 or later. Earlier versions of Domino
Designer use the name as the label.
v If applicable, specify a target frame (in the current frameset) to be the target of the action. For
example, if you create an action that opens a view, specify the name of the frame in which the
view should open.
v Select the display type for the action. You can choose Button, Checkbox, or Menu separator.
Checkbox lets you show the state of an item (checked or unchecked). If you choose Checkbox, you
can enter a value in the Value field (for example, a formula that evalutes to true of false). You can
also highlight the Click event in the Objects list of the Programmer’s pane to enter a Click value. If
you want the action bar’s state (checkbox) to be reevaluated when a different document becomes
current, make sure to check the ″Evaluate actions for every document change″ option at the
Options tab of the Views Properties box. You can also use the @GetViewInfo function.
If you choose Menu separator, a menu separator appears and there is no action. You can also use
menu separators between subactions of an action drop-down list.
v Check ″Include action in Action bar″ to make the action available as an item in the action bar.
v If the action is a button action, you can also choose to have only the icon appear in the action
control bar.
v Check ″Right align action control″ to have the action control aligned on the opposite side of
whatever is set in the Action Bar Properties box. Note that it may not necessarily be right aligned.

244 Application Development with Domino Designer 7


v Check ″Include action in Action menu″ to make the action available as a menu item in the Actions
menu.
v You can select an icon to appear on the action button. If you prefer a Notes graphic, select Notes
and then click Image to select a graphic for the icon from a set available in Notes.
If you prefer a customized graphic, select Custom. In the Image field, specify the name of an
image resource or click the folder icon to browse for an image resource. The image resource must
reside in the current database. You can specify the name of an image resource that does not yet
exist. Designer warns you that the image does not exist and that you must create it later. Click @
and specify a formula (or set of formulas) to display an image programmatically.
6. Click the Hide When tab to specify when to hide the action.
7. Click the Advanced tab and specify how Notes workflow proceeds after the user activates the action.
8. In the Info List of the Programmer’s pane, click Objects and select the shared action you just created.
9. To program the shared action to run one of the client or one of the Web program code types, choose
either Client or Web at the Run pull-down list.
Choose Client when the automated task will run in the Notes client. You can then select one of the
following Client code options:
v Simple actions
v Formula
v LotusScript
v JavaScript
v Common JavaScript
Choose Web when the automated task will run in a Web browser. You can then select one of the
following Web code options:
v JavaScript
v Common JavaScript
10. Save the shared action.

To create shared action notes


A shared action note is found only in multilingual databases and acts as a folder for shared actions of
one language. Each shared action note in a database contains the same actions. The difference between
the shared action notes is the language and the region to which they are set.

To create shared action notes in a multilingual database:


1. At the Design tab of the Database Properties box, check ″Multilingual database″ so that the database
is set as a multilingual database.
2. Click Shared Code in the Design pane.
3. Click Actions. At least one collapsible shared action note appears.
4. Select the shared action note and choose Design - Design Properties. The Design Document Properties
box appears.
5. At the Design tab, select the language and the corresponding region, if any, for all the actions
contained in this shared action note (for example, Portuguese as the language and Brazil as the
region).
6. For each new shared action note, set the language and region and make sure the note contains the
same shared actions as are found in the other shared action notes in this database.
7. Right click each shared action to check its Action ID. The Shared Actions Properties box appears. At
the Action Info tab for each shared action:
v Make sure each shared action in a shared action note has a different Action ID.

Chapter 10. Adding automation to applications 245


v Make sure the Action ID for a shared action is the same across shared action notes. For example, if
a Cancel action contained in the Danish shared action note is set to Action ID 16, the Cancel action
contained in the Turkish shared action note should also be set to Action ID 16.

To delete a shared action note


1. Select the shared action note.
2. Choose Edit - Delete.

Note: When you delete a shared action note, you delete all the shared actions it contains.

To insert a shared action


1. Open the view, folder, form, subform, or page where you want to use the shared action.
2. Choose Create - Action - Insert Shared Action. The Insert Shared Action dialog box appears.
3. Select a shared action and click Insert for each shared action you want to insert. Each shared action is
added to the Action pane and also to the Objects list for the design element.
4. Click Done when you are finished inserting shared actions.
5. In the Info List, you can click Objects and select an action, or select an action in the Action pane.

The next time you use the view, folder, form, subform, or page, the shared action is available.

To edit shared actions


To edit a shared action, open the database with the shared action. Click Shared Code, then Actions, and
then double-click the shared action you want to edit. The Shared Action Properties box appears.

Creating a button
1. Open the design element to which you want to add the button (a page, view, frameset, form, folder,
or navigator), or edit a document.
2. Click where you want to add the button and choose Create - Hotspot - Button.
3. On the Button Info tab of the Button Properties box, you can set the following properties:
v Label: Enter the text you want to appear in the button.
If you enter text that is wider than the button and you want it to wrap automatically, check ″Wrap
label text as needed.″
v Width: Specify a value, in inches, for the width of the button.
You can also choose one of the following width options:
Maximum width -- specifies that the value in the Width field is the maximum width for the button.
The width may be less if the width of the button text is less.
Minimum width -- specifies that the value in the Width field is at least the width specified. The
button may be wider if the button text is wider.
Fixed width -- specifies that the value in the Width field is the actual width of the button. If you
checked ″Wrap label text as needed,″ any text wider than the fixed button width wraps
automatically. If you have not checked ″Wrap label text as needed,″ any text wider that the fixed
button width may disappear.
Fit Content -- sets the width of the button to fit the width of the text you specified in the Label
field. If you choose this option, you cannot set the width manually.
v Style: Specify a color for the button background. You can also choose to have a button with square
edges or rounded edges.
v Type: Use this setting if you are creating a hotspot button for a template dialog box and you want
the button to behave in a certain way (such as closing the dialog box after the button is pressed).
You can create the following types of buttons:

246 Application Development with Domino Designer 7


Type of button Description
Normal Normal is the default button. Pressing a normal button performs the button action
but does not close the dialog box it is part of.
OK When clicked in a template dialog box, this button closes the dialog box with an OK
operation and displays a standard Windows OK message. This button is not
compatible with Lotus Domino Designer Release 5 and earlier.
Cancel When clicked in a template dialog box, this button closes the dialog box with a cancel
operation and displays a standard Windows Cancel message. This button is not
compatible with Lotus Domino Designer Release 5 and earlier.
Help This button is active on Macintosh platforms only. When clicked, it displays a help
message. This button is not compatible with Lotus Domino Designer Release 5 and
earlier.
Default Check this box for the hotspot button you want to become the default button for the
template dialog box. If the user presses Enter when the focus is not on a button, this
is the default button that is pressed instead. Note that a dialog box can have only one
default button.

The advantage of using the OK, Cancel, and Help buttons is that you can place the buttons
anywhere you want. Previously, these buttons could be aligned only vertically on the right or
horizontally on the bottom of the dialog box. In addition, you can associate some LotusScript with
these buttons; however, the buttons always close the dialog box despite any code.
If you use the OK or Cancel buttons, the template dialog box must be invoked using @DialogBox
with the [NOCANCEL] and [NOOKCANCEL] paramaters.
4. (Optional) On the Hide When tab, specify when to hide the button.
5. In the Info List, click Objects and select the button you just created.
6. To program the button to run one of the client or one of the Web program code types, choose either
Client or Web at the Run pull-down list.
Choose Client when the automated task will run in the Notes client. You can then select one of the
following Client code options:
v Simple actions
v Formula
v LotusScript
v JavaScript
v Common JavaScript
Choose Web when the automated task will run in a Web browser. You can then select one of the
following Web code options:
v JavaScript
v Common JavaScript
7. Save the design element or document.

Other button tasks


Button task Steps to perform
To change properties Click the button and choose Button - Button Properties.
To change automation In the Info List, click Objects, select the button in the Objects list and edit the
programming tasks in the script area.
To delete Click the button and choose Edit - Delete.
Call an agent Use the @Command([RunAgent]) or the OpenAgent URL.

Chapter 10. Adding automation to applications 247


Creating a text pop-up
A text pop-up can appear on a page or form and displays text to a user when a click or mouse-over
occurs.
1. Open the page or form you want to add the pop-up to, or edit a document.
2. Select text or an image to associate with the text pop-up.
3. Choose Create - Hotspot - Text Pop-up.
4. On the Hotspot Info tab of the HotSpot Pop-up Properties box, do one or more of the following:
v Enter the text for the pop-up.
v Select whether to pop up the text when the user mouses over or clicks the hotspot.
v Select whether to identify the hotspot with a border and whether to use the highlight color or a
default green.
5. (Optional) On the Hide When tab specify when to hide the pop-up.
6. Save the form or document.

Other text pop-up tasks


Text pop-up task Steps to perform
To change properties Cick the pop-up and choose Hotspot - Hotspot Properties.
To delete, but keep the associated text Click the pop-up and choose Hotspot - Remove Hotspot.

Example: Text pop-ups


Users register for conferences using a form you designed, but they frequently enter an incorrect e-mail
address. You want to give users more information about what you need in the field. Create a text pop-up
to display the information when they mouse over the field label.
1. Open the form.
2. Select the field label.
3. Choose Create - Hotspot - Text Pop-up.
4. On the Hotspot Info tab of the HotSpot Pop-up Properties box, do the following:
v Enter the following text:
Specify your Notes mail address, not your internet mail address. For example, specify "Ken Jones@ABC"
not "kjones@abc.com."
v Select ″Pop-up on mouse over.″
v Select ″Show border around hotspot″ and ″Use highlight color.″
5. Save the form.

Creating a formula pop-up


A formula pop-up completes a programmed task using only formulas. The results display in the pop-up
on the page or form.
1. Open the page or form you want to add the pop-up to, or edit a document.
2. Select text or an image to associate with the formula pop-up.
3. Choose Create - Hotspot - Formula Pop-up.
4. On the Info tab of the HotSpot Pop-up Properties box, do one or both of the following:
v Select whether to pop up the formula when the user mouses over or clicks the hotspot.
v Select whether to identify the hotspot with a border and whether to highlight the text.
5. (Optional) On the Hide When tab, specify when to hide the pop-up.

248 Application Development with Domino Designer 7


6. In the Info List, click Objects and select the hotspot you just created.
7. Enter its formula.
8. Save the form or document.

Note: Consider using formulas that display information, such as @Time. Also, do not use formulas that
take action, such as @OpenView.

Other formula pop-up tasks


Formula pop-up task Steps to perform
To change properties Click the hotspot and choose Hotspot - Hotspot
Properties.
To delete but keep the associated text Click the hotspot and choose Hotspot - Remove Hotspot.
To change the formula Click the Hotspot entry in the Objects list and edit the
formula in the script area.

Creating an action hotspot


In Lotus Notes, an action hotspot completes a programmed task using simple actions, formulas,
LotusScript, JavaScript, or Common JavaScript. Use Common JavaScript so that the action hotspot can be
used in both a Web browser and the Notes client.
1. Open the form, subform, or page on which you want to add the action hotspot.
2. Select text or an image to associate with the action hotspot.
3. Choose Create - Hotspot - Action Hotspot.
4. On the Hotspot Info tab of the Action HotSpot Properties box, specify the frame in which you want
the data to display when the user clicks the link hotspot. You can also choose to have a border appear
around the hotspot.
5. (Optional) On the Hide When tab, specify when to hide the hotspot.
6. In the Info List, click Objects and select the action you just created.
7. Program the action hotspot to run one of the client or one of the Web program code types by
choosing either Client or Web at the Run pull-down list.
Choose Client when the automated task will run in the Notes client. You can then select one of the
following Client code options:
v Simple actions
v Formula
v LotusScript
v JavaScript
v Common JavaScript
Choose Web when the automated task will run in a Web browser. You can then select one of the
following Web code options:
v JavaScript
v Common JavaScript
8. Save the form, subform, or page.

Other action hotspot tasks


Action hotspot task Steps
To change properties Click the hotspot and choose Hotspot - Hotspot Properties.

Chapter 10. Adding automation to applications 249


Action hotspot task Steps
To delete, but keep the associated text Click the hotspot and choose Hotspot - Remove Hotspot.
To change automation Click the Hotspot entry in the Objects list and edit the programming
in the Script area.
To call an agent Use the @Command([RunAgent]) or the OpenAgent URL command.

Creating a program for an event


Use event programming to run tasks that users shouldn’t have to activate themselves and that are very
specific. Event programming is particularly useful when the timing of the program must be precise or the
tasks are associated with a particular design element.
1. Open the design element to which you want to add automation.
2. In the Info List, click the Objects tab and select the event.
3. From the Run list, choose either Client or Web.
4. Depending on whether you chose Client or Web, you can choose from the following:
v Simple actions
v Formula
v LotusScript
v JavaScript
v Common JavaScript
5. Save the event.

Creating an agent
Before you begin, plan your agent carefully. For example, decide what type of agent you want (simple
action, formula, LotusScript, imported Java, or Java), what it will act upon, where it will run, how it will
be invoked, whether it will perform restricted or unrestricted operations, and under whose ID it should
run (run on behalf of).
1. In Designer, open the database in which you want to create an agent.
2. Choose Create - Design - Agent. The Agent Properties box appears.
3. On the Basics tab, enter a name for the agent in the Name field.
Note that names and aliases should be unique. (Agents that call other agents look for the first
instance of a name and will attempt to run that agent. If more than one agent has the same name,
you may run into problems.)
4. Optionally, enter a comment in the Comment field. The comment appears when you view the list of
agents.
5. Click Shared if this agent will be used by other users. A shared agent is one that other users have
access to. Note that ownership of a shared agent can be reassigned to another user who saves or
re-signs the agent.
Click Private if you want the agent to be an agent that only you can run. In Lotus Notes, private
agent are not available on the Actions menu. In Domino Designer, anyone with Designer level access
or higher can see and run a private agent.
Beginning with Lotus Domino Designer 6, you have the option of converting a private agent to a
shared agent or a shared agent to a private agent.
6. If the agent searches for text in documents, you can specify the following settings in the Options
section:
v Check ″Store search in search bar menu″ to display your search query in the search bar.

250 Application Development with Domino Designer 7


v Check ″Store highlights in document″ so that your search matches are highlighted in the searched
documents.
7. To run an agent without having to wait until it completes, check ″Run in background client thread.″
Note that you should check this option only if the agent (or the top-level agent that calls this agent)
is triggered by ″On event - Action menu selection.″
To get the full benefit of this feature, the database should reside on a server and the agent must be
invoked via the client.
If you check this box and the agent references front end classes, the user receives a run-time error.
8. In the Runtime section of the properties box, choose one of the following triggers for the agent.
Different options appear depending on the trigger you choose.
v On event - see the topic ″Triggering an agent on an event″ for more information on the event
options.
v On schedule - see the topic ″Triggering an agent on a schedule″ for more information on the
schedule options.
9. Click the Security tab of the Agent Properties box to set up security for the agent.
10. Close the Agent Properties box after you have filled in the necessary fields.
11. From the Run list in the Programmer’s pane, choose one of the following to define the agent’s
automated components:
v Simple actions
If you choose Simple actions, click the ″Add Action″ button to add a simple action.
v Formula
v LotusScript
v Java
v Imported Java
12. If you want to create a search, select the Object tab and then the ″Document Selection″ event in the
Programmer’s pane. Then use the ″Add Condition″ button to invoke the Add Condition dialog box.
Note that this way of creating a search replaces the Search button found in earlier versions of
Designer.
13. Save the agent.
Note that the agent is being saved and signed with your current ID.

Scheduled agents are enabled by default when first created and existing scheduled agents that are edited
are saved with their current state of enabled or disabled.

For additional information on using the Enable, Disable, and Sign buttons, see the topic ″Useful agent
procedures″ later in this chapter.

For additional information on agent security, see the topic ″Security for agents on servers and the Web″
later in this chapter.

For troubleshooting information, see the topic ″Troubleshooting agents″ later in this chapter.

Triggering an agent on an event


Once you have created an agent, you must choose whether to trigger the agent on an event or on a
schedule. To trigger an agent on an event:
1. On the Basics tab of the Agent Properties box, click ″On event.″

Chapter 10. Adding automation to applications 251


2. Choose one of these events in the following table:

Event to trigger agent Use for


Action menu selection User-activated agents or for WebQuerySave or WebQueryOpen agents.
Agent list selection Agents that are only to be called by other agents and for agents that are still being
developed or are run from Designer.
Before new mail arrives Processing mail before it is deposited in the mail databases; for example, to move
incoming mail to a folder.

With this option, the agent runs before the message is listed in the database.
Therefore, be careful what other options you choose. For example, do not use the
″Mark Documents Read″ simple action because documents will always be marked
unread when they are listed in the database.

Note that this option is limited to one agent per database.


After new mail has arrived Processing incoming mail: to respond to it, forward it, or file it.

Interactive functions and functions that read or modify data external to the current
document are ignored when documents are mailed into the database. For example:
@DbColumn, @DbCommand, @DbLookup, @MailSend, @Prompt, @Command, or
@PostedCommand are all ignored.

Note that you can use this option multiple times within the same database.
After documents are created Workflow tasks where a task is performed based on new or changed documents. This
or modified trigger is actually a scheduled agent handled by the Agent Manager and can execute
either on the local Notes client or on a server.

When you select ″After documents are created or modified,″ an ″Edit settings″ button
appears. If you click the button, the Schedule dialog box appears. Here you can set a
start and end date for the agent, tell the agent not to run on weekends, and either
choose a server for the agent to run on or choose the local Notes client. You can also
specify that the server is chosen when the agent is enabled.

The delay time using this agent varies between 5 to 30 minutes, depending on the
server load.
When documents are pasted Documents that are pasted into the database and need to be modified as they are
being pasted. Note that this event requires action by the user and does not happen in
the background.

Paste-activated agents cannot use @Command or @PostedCommand.

3. If you selected ″Agent menu selection″ or ″Agent list selection,″ choose one of the following targets
from the Target list. These are the documents on which the agent will run.
v All documents in database
v All new and modified documents
v All unread documents in view
v All documents in view
v All selected documents
v None - choose None for any agent that is not working with a specific set of documents. For
example, choose None if you have an agent that displays a message to the user. None also lets you
use @commands.

Note: Beginning with Lotus Domino Designer 6, ″Run Once″ is no longer listed as an option on the
Targets pull-down list. (″Run Once″ was often used to set up Web agents.) Choose ″None″ instead.

252 Application Development with Domino Designer 7


Triggering an agent on a schedule
Once you have created an agent, you must choose whether to trigger the agent on an event or on a
schedule. To trigger an agent on a schedule:
1. On the Basics tab of the Agent Properties box, click ″On Schedule.″
2. In the list next to the Schedule button, choose one of the schedules listed in the following table.
Note that the Web does not support scheduled invocation of agents; however an agent on the Web
can be triggered in other ways, such as through Tools/Macros or from the URL.

Schedule for agent Use for


More Than Once a Day High-priority databases, such as those critical to a business process and for databases
that replicate several times a day, such as workflow applications that route documents for
approval.

Be aware that if you schedule very frequent runs (for example, every 5 minutes), the
server’s performance could be adversely affected.
Daily Activities that are important but that will not cause a delay if they are only generated
once a day. Examples include mailing news wire articles or generating low-priority
assignments.
Weekly Routine tasks, such as generating summary reports and sending reminders.
Monthly Low-priority maintenance tasks, such as archiving documents and distributing company
newsletters.
Never Agents that you do not want to run in particular circumstances. For example, use this
run option for agents that do run on the Web or for agents that are called by other
agents.

3. Once you make a choice from list, click the Schedule button to display the Schedule dialog box. You
can add more details about running the agent. For example:
v If you specified ″More than once a day,″ you can specify how often you want the agent to run on
each day. You can also specify that the agent not run on weekends.
v If you specified Weekly, you can specify the day of the week and time of day for the agent to run.
v If you specified Monthly, you can specify a day of the month and time of the day for the agent to
run.
4. In the same Schedule dialog box, you also specify the servers on which you want the agent to run.
You can choose from the ″Run on″ list. Alternatively, you can have users choose the server.

Server agent runs on Use


Local The agent runs only on the client. Use this option to schedule agents to run in the
background on the local Notes client. The database containing the agent must be a
local database. The agent will run with the rights of the current Notes ID.

Note that for scheduled agents to run on the local Notes client, the user must first
select ″Enable scheduled local agents″ on the Basics tab of the User Preferences dialog
box (Choose File - Preferences - User Preferences).
Any server The agent runs on any server that the agent is available on. When agents run on
multiple servers and they are changing documents in databases that are replicated,
you should specify the servers they run on to prevent replication conflicts. Then, set
up the databases’ replication schedules so they don’t interfere with the agents’
scheduled runs.

Note that this option does not cause problems if you are using copies (instead of
replicas) of the database.
Specific server The agent runs only on the single server you select from the list of available servers.

Chapter 10. Adding automation to applications 253


Server agent runs on Use
Choose when agent is Checking this option prompts users to select a server when the agent is enabled. This
enabled option is useful for distributing agents in ready-to-use applications.

5. From the Target pull-down list, select the documents in the database the agent will run on. You have
two choices:
v All documents in database
v All new and modified documents
These options are not supported on the Web.

If you paste, modify, or enable a scheduled agent, the agent will run immediately if it has missed running
on the day of the changes.

Note: Agents are scheduled according to the interval you set up, not the exact time of day. For example,
if you schedule an agent to run hourly, it runs about one hour after the last time it ran.

Agents that miss their scheduled run


If a scheduled agent is edited (for example, enabled, modified, saved, or pasted), it will usually run
immediately if it has missed its scheduled run. This is true for agents scheduled monthly and weekly. It
is partially true for agents scheduled daily.

If a agent scheduled to run daily misses its scheduled run because it was disabled, it will run if it is
enabled within half an hour of the scheduled run. However, If a scheduled agent is saved, pasted, or
modified, it will run immediately if it has missed its schedule.

Useful agent procedures


To view a list of agents
1. Open a database in Designer.
2. Click Shared Code - Agents in the Design pane. A list of agents appears in the Work pane.

When you view a list of agents in the Work pane, an icon may appear next to the name of a scheduled
agent. The icons are:
v Check mark with a 6 next to it - the scheduled agent is enabled and runs only on Lotus Notes Domino
6 or later (or on Lotus Notes/Domino R5.08 or later).
v Check mark with a 5 next to it - the scheduled agent is enabled and runs only on Lotus Notes Domino
R5.07 or earlier.
v Check mark - the scheduled agent is enabled and runs on any version of Notes.
v A yellow X - the scheduled agent is disabled.

The list of agents also gives you important information about each agent. You can easily view such
information as the agent name, its alias, trigger, modification date, the person who modified it last, and
whether the agent works in Notes and on the Web.

To copy an agent
1. Open a database in Designer.
2. Click Shared Code - Agents in the Design pane. A list of agents appears in the Work pane.
3. Select the agent.
4. Choose Edit - Copy.

254 Application Development with Domino Designer 7


To delete an agent
1. Click Shared Code - Agents in the Design pane. A list of agents appears in the Work pane.
2. Select the agent.
3. Choose Edit - Cut.

To select multiple agents


1. Click Shared Code - Agents in the Design pane. A list of agents appears in the Work pane.
2. Click the first agent and do one of the following:
v Press CTRL and hold while you click the next agent.
v If selecting more than two agents, press CTRL while you click the next agent.
v To select a range of consecutive agents, press SHIFT while you select the first and last agent in the
range.

If you have Designer access or above, you can disable shared scheduled agents to prevent servers from
running them. This is useful for debugging a problem with an agent. Designers can still run disabled
agents by choosing View - Agents, selecting an agent, and choosing Actions - Run. After you re-enable
them, scheduled agents resume their schedule.

To disable individual agents


1. Click Shared Code - Agents in the Design pane. A list of agents appears in the Work pane.
2. Select the agent and click the Disable button. Note that the agent is re-signed.
The check mark icon next to the agent name disappears and an X icon appears in its place.

To disable all agents in a database


1. Choose File - Database - Properties.
2. On the Database Basics tab, check ″Disable background agents for this database.″

Note: If you disable agents through the Database Properties box, the agents are not re-signed and the
Enable/Disable state of each agent is not changed. Unchecking this box does not necessarily enable all
agents. It only allows those already enabled to run.

To enable a disabled agent


1. Click Shared Code - Agents in the Design pane. A list of agents appears in the Work pane.
2. Select the disabled agent. (It should have a yellow X icon next to the agent name.)
3. Click Enable.
The X icon disappears and a check mark icon appears next to the name of the agent. Note that the
agent is re-signed.

By default, Web agents run under the identity of the agent author (the person who saved the agent). To
run agents under the identity of the Web user, double click the name of the agent in the Work pane. On
the Security tab of the Agent Properties box, check ″Run as Web user.″

To sign an agent
1. Select the agent.
2. Click Sign.

Chapter 10. Adding automation to applications 255


Examples of agents to run before Web users open or save documents
To perform error checking, field validation, and other processing before Web users open or save
documents, create a shared agent that runs manually. Then write a formula that uses
@Command([RunAgent]) or @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 aren’t 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 aren’t possible with
@commands or collecting statistics about who opened documents and when they did so.

Note: WebQueryOpen agents run when the user opens a form or document, but do not run when the
user saves a document. This means that computed fields set by a WebQueryOpen agent are not saved
when the user submits a document. To make sure computed fields are saved, you can either recalculate
them in the WebQuerySave agent or set the form property ″Generate HTML for all fields.″

WebQuerySave events
A WebQuerySave event runs the agent after field input validation formulas are run and before the
document is actually saved to disk or mailed. The agent can modify the document or use the document
data to perform other operations. The document is automatically saved after the agent runs. Do NOT
have the agent explicitly save the document (for example, by calling NotesDocument.Save) because an
explicit save could cause incorrect results.

A WebQuerySave agent can produce output to be sent back to the user. For example in a LotusScript
agent, you can use the Print command to return raw HTML. If the agent produces output, then the form
should not have a $$Return field because Domino will return only the agent output and ignore the field.

Examples for using this agent include:


v Performing complex field validation. If the document does not pass validation, you can prevent
Domino from saving the document by changing the value of the SaveOptions field to ″0″ on the form.
v Simulating CGI programs that run on user-supplied data by programming a WebQuerySave event and
changing the value of the SaveOptions field to ″0″ on the form. When the agent runs, you can collect
field values from the filled-out form without generating a new Notes document.
v 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.

Note: The SaveOptions field must be an existing field on the form, which the WebQuerySave agent
changes the value of. If the agent creates the SaveOptions field, the form will be saved regardless of the
value in that field.

Setting up agent security using the Security tab


Beginning with Lotus Domino Designer 6, you can set up basic security for an agent by using the
Security tab of the Agent Properties box. This tab contains the following options:

Option Description
Run as Web user Checking this causes the agent to run with the effective user name of the Web user.

256 Application Development with Domino Designer 7


Option Description
Run on behalf of Lets you specify on whose authority this agent can run. Note that restricted signers
can run agents only under the same authority as their own (that is, the restricted
signers enter only their own name or else the agent returns an error at run time).
Unrestricted signers and signers with rights to run ″On behalf of anyone″ can run
agents on behalf of anyone. Whoever you specify in this field has to be included in
the ACL of any database being accessed.

If the agent is sending mail or creating documents, this name is used as the mail
sender or document author.
Note: This feature is not supported on releases earlier than Lotus Domino Designer
6.
Allow remote debugging Checking this enables the agent to be debugged through a remote debugger. This
property applies only to LotusScript agents.
Restricted operations Lets users who have unrestricted rights specify whether the agent should run in
restricted mode, unrestricted mode, or unrestricted with full administration rights
mode. By default, the value is set to restricted mode because this is the safest
setting. For users who have restricted rights, this option has no effect on the agent.

You have the following choices from the drop-down list:


v Do not allow restricted operations -- the agent is not allowed to perform
restricted operations. Note that this is the most secure choice. The reason the
agent cannot perform restricted operations is that the agent has rights that are
restricted.
v Allow restricted operations -- the agent can perform restricted operations because
it is has been granted unrestricted rights. Note that this is a less secure choice
than the previous one and grants the agent more power.
v Allow restricted operations with full administration rights -- the agent can
perform restricted operations and can do so with full administration rights. This
choice grants even more power to the agent because the agent now has been
granted unrestricted rights and given full administration rights. Use this choice
with caution.

For more information on restricted operations, see the topic ″Restricted LotusScript
and Java agent operations″ later in this chapter.
Profile this agent Check this box to monitor calls to Domino Objects in agents and their elapsed
times. For agents written in LotusScript or Java only.
Compile Java code with Checking this enables the Java code to be debugged through a remote debugger.
debugging information This property applies only to Java agents.
Allow user activation Checking this box allows users with ACL editor access to enable this agent. This
allows a scheduled agent on the server to be enabled or disabled without resigning
the agent.
Note: If this box is checked and someone enables the agent, the agent is not
re-signed. If this box is not checked and someone (with Designer access or above)
enables the agent, the agent is re-signed.
Default access for viewing and The default level for viewing and running the agent is ″All readers and above.″ You
running this agent can deselect this field and choose who you want to have default access for viewing
and running the agent.
Allow public access users to Lets users who have public access to documents in a database view and run the
view and run this agent agent.

Security for agents on servers and the Web


For agents created and run in Notes databases stored on servers or run from the Web, you can set up
several levels of security controls to prevent unauthorized operations.

Chapter 10. Adding automation to applications 257


Who can create agents?
To control who can create agents that run on servers, use database ACLs.

Note: Web users cannot create agents.

To create Access needed


Private agents Reader access or higher and must have ″Create private agents″ enabled
in the ACL
Private agents using LotusScript and Java Reader access or higher and must have ″Create private agents″ and
″Create LotusScript/Java agents″ enabled in the ACL
Shared agents using simple actions and Designer access or higher
formulas
Shared agents using LotusScript or Java Designer access or higher and must have ″Create LotusScript/Java
agents agents″ enabled in the ACL

Who can run agents?


To control who can run agents on servers, use the Server document in the Domino Directory and
database ACLs. See the topic ″Controlling agents that run on a server″ in the Lotus Domino
Administrator Help for more information.

Private agents
To control who can run private agents, open the Server document in the Address Book and click the
Security tab. In the Programmability Restrictions section:
v If everyone who can access the server can run private agents, leave ″Run private agents″ blank.
v If only specific users can run private agents, specify their names in ″Run private agents.″

Web users cannot run private agents.

Shared agents
To control who can run shared agents, use the database ACL. Users with Reader access or higher can run
shared agents.
v If users are allowed to run shared agents, assign them Reader access or higher.
v If users are not allowed to run shared agents, do not list them in the ACL or assign them Depositor
access.

LotusScript/Java agents
LotusScript and Java include operations that have full access to the server’s system and can manipulate
system time, file I/O, and operating system commands. Users or groups with unrestricted access can run
an agent that includes any of these operations in the LotusScript and Java components. Users or groups
with restricted access can include most operations. The only restricted commands are those that allow
access to the server’s system.

CAUTION:
Unrestricted Java and LotusScript agents can potentially violate security. Only a limited number of
trusted users should have unrestricted rights.

Where can agents run?


To control whether agents are allowed to run on servers, use the Server document in the Address Book.
Click the Security tab. In the Server Access section:

258 Application Development with Domino Designer 7


v If everyone running an agent that accesses the server is allowed to access the server, leave ″Access
server″ blank.
v If you don’t want users accessing the server either directly or through agents, specify the user names in
″Access server.″ Then, if a user who is not specified attempts to run an agent that accesses the server,
the agent is not run. You can also specify user names in ″Not access server.″

Note: These restrictions apply to agents running from other servers or from a client. Agents that are
already scheduled to run on the server will not be affected by the Server Access section.

What operations can agents run?


To control which documents agents can process, Domino checks the ACL of the database where the
documents are stored, as follows:
v For agents that use simple actions, LotusScript, and Java, Domino checks the user’s ACL.
v For agents that use formulas, Domino checks the replica ID of the database in which the agents were
created. Therefore, to ensure that agents using formulas can access documents in other databases, you
must list the database replica ID in each database the agent will access.

To control whether agents are allowed to create databases, use the Server document in the Address Book.
Click the Security tab. In the Server Access Section:
v If everyone is allowed to create databases, leave ″Create new databases″ blank. Then, anyone running
an agent that creates new databases can do so on the server.
v If you don’t want users creating databases, specify the user names of people allowed to create
databases in ″Create new databases.″ Then, if a user who is not specified runs an agent that creates a
database, an error is reported and the database is not created.

When are restrictions checked?


Domino checks the security restrictions differently depending on whether the agent is running:
v Locally or on the server
v In the foreground or background
v If the agent is started from the Web or the Notes client

Locally on Notes
An agent runs locally when:
v It runs within a Notes client database.
v You choose ″Local″ from the ″Run on″ list for a scheduled agent.
v A user starts the agent from the Actions menu in the Notes client, from the Agent - Run menu in
Designer, from the ″When documents Have Been Pasted″ trigger, or from calling the agent by
agent.run.

When an agent runs locally, Notes does not check security restrictions, unless you have set the Enforce
ACL option. (To set the Enforce ACL option, choose File - Database - Access Control and then click the
Advanced icon.)

On the server
An agent runs on the server when it is running in a database stored on a server and it is started by one
of the following:
v Before new mail arrives
v After new mail arrives
v If documents have been created or updated
v On schedule more than once a day

Chapter 10. Adding automation to applications 259


v On schedule daily
v On schedule weekly
v On schedule monthly
v Called by an agent via agent.runonserver (the agent being called must reside on the server)

If the agent is running on a server, Domino checks all security restrictions.

Foreground or background
An agent runs in the foreground when a user starts it from the Notes Actions menu, selects it from the
Designer Agents list, or clicks an Action button. When agents run in the foreground, security restrictions
are not checked.

An agent runs in the background when it is scheduled or it is triggered by an event (for example, when
documents are modified) or when it is called by agent.runonserver. When agents run in the background,
Domino checks security restrictions.

From the Notes client or the Web


Agents run in the Notes client or on the Web based on the effective user. The effective user is the user
under whose authority the agent runs. The effective user depends on the environment in which the agent
runs.

Agent type Effective user


Notes client agent Current user ID
Web agent One of the following:
v Current Web user
v Agent signer (agent owner)
v On behalf of (set in the Security tab of the Agent Properties box).
Scheduled agent Either:
v Agent signer (agent owner)
v On behalf of (set in the Security tab of the Agent Properties box).

When a Web user runs an agent, the agent also runs using the rights of the effective user and Domino
checks the effective user’s rights to access the database. However, you can set up the agent so that
Domino checks the invoker’s rights to access the database instead of the effective user’s rights. Checking
the invoker’s rights can provide more security.

To specify that Domino verify the invoker’s access to the database, follow these steps:
1. Double-click an agent name in the agent list.
2. Click the Security tab.
3. Check ″Run as Web user.″

When ″Run as Web user″ is checked, Domino prompts Web users for their name and password when
they attempt to run the agent. Domino uses the login information to check for the invoker’s rights in the
database ACL.

Security controls for agents that are called by agents


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

260 Application Development with Domino Designer 7


v If the first agent uses LotusScript or Java:
Domino checks each agent that is called against the rights of the signer of each agent.

Troubleshooting agents
You can experience problems running agents at several points during agent development, deployment,
and implementation. Try the following to help diagnose any problems.
v Run the agent on the Notes client.
v Simulate an agent run (for all types of agents).
Before running an agent on a live database, test it by simulating a run. The test also diagnoses whether
the agent will run by checking security and schedule settings.
v Review the Agent Log (for all types of agents).
The Agent Log displays information about when the agent last ran and whether it ran successfully.
v Use the Notes server console (for all types of agents).
There are three server console commands available to display information about agent scheduling,
status of agent queues and control parameters, and status of agent debugging settings that are in effect.
v Set up the Agent Manager debug information (for all types of agents).
You can specify that the Agent Manager record debug information about any combination of the
following: control parameters, events, loading reports, memory warnings, performance statistics,
execution reports, and scheduling. Messages appear on the server console and are recorded in
LOG.NSF.
v Run commands in the LotusScript debugger (for foreground agents built with LotusScript.)
Choose File - Tools - Debug LotusScript and run the agent. The LotusScript debugger appears and you
can run any debugging command in the agent as you would for any LotusScript program.
v Track information with the NotesLog classes (for background agents built with LotusScript or Java).
The NotesLog class is added to your agent code and can capture information you want to track. The
NotesLog class records the information in the Agent Log.
v Check the Notes log database (LOG.NSF).

Testing agents
You can test an agent in the following ways:
v For agents that do not call other agents, use the Test menu command.
v For agents that use LotusScript, use the LotusScript debugger.
v For more complicated agents, create a test copy of the database you can work with before you work
with the original database.

To use the Test menu command


1. Select the agent and choose Actions - Test.
2. Read the Agent Log and check:
v How many documents would be processed (for formula and simple action agents)
v What action would be taken if the agent were actually run
3. If necessary, make corrections and run the test again.

To use the LotusScript debugger


1. Choose File - Tools - Debug LotusScript.
2. Run the agent and the LotusScript debugger appears. You can then review each step as the agent the
agent runs.
3. You can also use message boxes and print statements.

Chapter 10. Adding automation to applications 261


To create a test database
You may wish to make a test copy of an existing database before working with the actual 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.

Note: Java agents have a console tool to which agents can print messages. In Designer, choose File -
Tools - Show Java Debug Console. In addition, you can use the remote debugging tool (File - Tools -
Remote Debugging), which allows remote debugging of the LotusScript in an agent script and allows the
monitoring of the execution of Java agents.
1. Choose File - Database - New Copy to make a test copy of the database, with documents.
If the agent works on mailed documents, the test database must be on a server, and a Mail-in
Database document must exist in the Address Book.
2. Create test documents:
v If the agent works on mailed documents, mail a few documents to the test database.
v If the agent works on pasted documents, paste a few documents into the test database.
3. (Optional) Create a debug document to write values to.
4. Run the agent.
5. Use other available debugging tools to catch errors and make corrections.
6. Rerun the agent until it is working correctly.
7. Copy the tested agent to the live database.

Profiling agents and Web services


Calls to Domino Objects in agents or Web services written in LotusScript or Java can be monitored and
their elapsed times reported.

To enable profiling in an agent or Web service, select the Security tab of the properties box and check
″Profile this agent″ or ″Profile this web service.″ Profiling occurs each time an enabled agent or Web
service runs. Agent profiling occurs on both the Notes client and Domino server.

To view the profiling results for the latest run, select the agent and choose Agent - View Profile Results,
or select the Web service and choose Design - View Profile Results.

The results are presented in a document based on the hidden form $BEProfile. The result document
contains a heading listing the name of the agent or Web service and the creation time. The Body item of
the result document contains a table with a row for each Domino Objects method called and 5 columns:
v Class -- The name of a Domino Objects class using normalized names such as Session, Database, and
Document.
v Method -- The name of a Domino Objects method or property using normalized names such as
CurrentDatabase, AppendItemValue, and Save.
v Operation -- For properties, the type of operation: Get or Set.
v Calls -- The number of times the method or property was called.
v Time -- The amount of time the calls consumed in milliseconds. The symbol ″<″ means not enough
time to calculate.

The LotusScript NotesAgent class contains a new method GetPerformanceDocument which returns the
profiling results for the agent as a NotesDocument object.

262 Application Development with Domino Designer 7


Viewing the agent log
Every time an agent runs, it writes a log report with the following information:
v When it ran
v The number of documents it processed
v The actions it took on the documents

Each time an agent runs, it writes over the previous log report. Domino stores the Agent Log with the
database. The Agent log stores accurate information on simple action agents and formula agents.
Information on LotusScript agents, Java agents, or agents calling other agents is not necessarily complete.

If you are running agents built with LotusScript or Java and the agents run in the background, you can
add the NotesLog class to your agent code to record run-time information in the Agent Log.

To view the most recent Agent Log:


1. Select a database and choose View - Agents.
2. Select an agent whose log you want to check and choose Agent - Log.
3. Review the information in the Log.

Notes server console commands


These server console commands support agent debugging:
v tell amgr schedule
Use this command to see if the agent is scheduled to run. If it doesn’t appear in the list when it
should, then you know to check its schedule, to check whether or not the agent is enabled, and to
check whether or not the database has background agents disabled.
This command does not list agents that are manually run from the Actions menu or Agents list.
v tell amgr status
Use this command to see where your agent is running (that is, in which queue) and what parameters
are in effect.
v tell amgr debug
Use this command to display and change the debugger settings. These settings apply to the Agent
Manager debugger that you enable in the NOTES.INI file.

Tell amgr schedule


This command lists each agent that is scheduled to run on the current day. It lists only agents that run in
the background. Check the list for the following information to make sure the agent is scheduled
correctly.

Display Description What to check for


First column: The Agent Manager queue that the agent If the agent is scheduled, make sure it is listed
currently is in. with an E or S. If it is listed, check that the
ESV correct time is listed. If the agent is not listed,
E: Eligible to run check the ″When should this agent run″ setting.
S: Scheduled to run If the agent runs when new mail arrives or a
document is created or updated, it should be
V: Waiting to run listed with a V. If it isn’t listed, check the ″When
should this agent run″ setting.

Chapter 10. Adding automation to applications 263


Display Description What to check for
Second column: S The event that activates the agent. If the agent has an incorrect event or isn’t listed
MU when its supposed to be, it means that you
S: Daily, weekly, monthly, or more than selected an incorrect ″When should this agent run
once a day schedule setting.″

M: New mail has arrived

U: One or more documents have been


created or updated
Time of day If the agent is scheduled to run daily, Check and make sure the agent is listed.
weekly, monthly or more than once a day,
the time of day the agent will run is listed.
Today If the agent is scheduled to run daily, Check and make sure the agent is listed.
weekly, monthly, or more than once a day
and the time it is supposed to run hasn’t
gone by, then ″Today″ is listed.
Agent Name The agent name that is scheduled to run.
Database Name The name of the database that the agent Make sure you’re looking at the correct copy of
works in. the agent.

tell amgr status


This command lists the number of agents in queues and other run-time statistics. Even though agent
names are not listed, you can check the queue information to determine if the queues are processing the
number of agents you would expect. You can also check the run-time statistics to see how the Agent
Manager is set up.

For example, Agent Manager status information includes:


v The number of agents in queues waiting for events, such as New Mail and Document Update.
v The number of agents in queues waiting for a scheduled time to elapse, such as the Scheduled Task
queue.
v The time period, such as Daytime or Weekend.
v The maximum amount of time that a LotusScript/Java agent is allowed to run.

tell amgr debug


This command lists the Agent Manager debugger settings you specified with the Debug_AMgr statement
in NOTES.INI. Use this command to make sure the debugger settings are correct and to change them
using the same options that are available for the Debug_AMgr statement, except *.

For example, to add options for the Agent Manager that you have already set up to display agent
debugging information (-e option):
tell amgr debug -e, -l, -m, -p

Agent Manager debugging information


You can specify that the Agent Manager record debugging information in these ways:
v Specify Debug_AMgr in NOTES.INI
Use this statement to provide debugging information about agent loading, scheduling, and
performance. When you specify Debug_AMgr, you can use the tell amgr_debug command at the Notes
console to change the settings.

264 Application Development with Domino Designer 7


Note: If you specify that the Agent Manager display all possible debugging information, agent
performance can be significantly affected.
v Specify Log_AgentManager in NOTES.INI
Use this statement to provide a subset of the information recorded with Debug_AMgr.
Log_AgentManager does not affect agent performance as much as Debug_AMgr could.

If you specify both statements, the Debug_AMgr settings take precedence.

Debug_AMgr
To specify that the Agent Manager record debug information, edit NOTES.INI and add the following
statement:
Debug_AMgr=option

where option can be one or more of the following:


v c -- list agent control parameters
v e -- list Agent Manager event information
v l (lower-case letter-L) -- list agent loading information
v m -- list agent memory warnings
v p -- list agent performance statistics
v r -- list agent run-time reports
v s -- list Agent Manager scheduling information
v v (verbose) -- list more information about agent loading, scheduling, and queues
v * -- list all of the information for all options

After you specify Debug_AMgr in NOTES.INI and you run an agent on a server, check the Notes console
and Notes Log (LOG.NSF) for the debugging information. Optionally, you can redirect the debug
information to be recorded in a separate file on the server. When you redirect the debugging information
to a separate file, performance can be affected. To redirect information, edit NOTES.INI and add the
following statement:
DEBUG_OUTFILE=<file-name>

If you run an agent on a database stored on your local workstation, you must redirect the output because
the Notes console is only on the server.

Log_AgentManager
To specify that the Agent Manager record less debugging information than with Debug_AMgr, edit
NOTES.INI and add the following statement:
Log_AgentManager=option

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

NotesLog Class
Use the NotesLog class in LotusScript and in Java agents that run in the background. Add the NotesLog
class to your agent code to record run-time information. It is particularly helpful for capturing variable
values, error handling, and verifying code logic. By default, the NotesLog class records information to the
Agent Log. When you set up items you want recorded, make sure you don’t exceed the Agent Log limit.

Chapter 10. Adding automation to applications 265


To use NotesLog, follow this LotusScript example that tracks the documents an agent is processing by
capturing the documents’ subject. The information is recorded in the Agent Log.
Dim agentLog As new NotesLog("Agent log")
Dim collection As NotesDocumentCollection
Dim db As NotesDatabase
Dim s As NotesSession
Dim count As Integer
Call agentLog.OpenAgentLog
Set s=New NotesSession
Set db = s.CurrentDatabase
Set collection = db.UnprocessedDocuments
Set note = collection.GetFirstDocument
count = collection.Count
Do While (count >0)
Subject = note.Subject
Call agentLog.LogAction("Processing:"+Subject(0))
Set note = collection.GetNextDocument(note)
count = count-1
Loop
Call agentLog.Close

Agent Log limit


The Agent Log can hold only 64KB of information. When the information written to it exceeds this limit,
the following message is displayed and the agent stops running:

Error executing agent <agent-name> in <database-name>. Memory allocation request exceeded 65,000 bytes.

Make sure that the information you want recorded to the Agent Log does not exceed this limit. If it does,
rework the NotesLog class code to record less information per run.

Simple actions for automation


Use the following simple actions with shared and unshared actions, buttons, action hotspots, picture
hotspots, and agents. To access a list of simple actions, select Simple actions from the Run pull-down list
and click Add Action.

Note that Web applications do not support simple actions.

Copy to Database
Copies the selected document to the database you specify. You can copy and paste selected documents
within the same database or to another database on the same server or another server. They are marked
as read in the target database.

To specify:
1. Click Choose Database.
2. Select the server and target database.

Copy to Folder
Copies the selected document to the folder you specify. You must create new folders before you can select
them. Copying a document from one folder to another does not remove the document from the source
folder. A duplicate of the document is not created; instead the document is displayed in a new place.

266 Application Development with Domino Designer 7


Delete from Database
Deletes the selected documents from the database. If there are replicas of this database on other servers,
documents deleted in this database are also deleted in the replicas unless ″Do not send deletions made in
this replica to other replicas″ is selected in your database replication settings (choose File - Replication -
Settings and click Send to see what the settings are).

Mark Document Read


Marks selected documents as read. Use this action to mark an unread document as read without opening
it or for reverting a document that was modified back to its read status because it doesn’t actually need
to be read again -- for example, if it has been modified by an agent.

Combine this action with one that changes field values. Then when users change the values in a
document, they can mark it read at the same time.

Do not use this option with an agent that is processing documents with ″Before New Mail Arrives.″

Mark Document Unread


Marks selected documents as unread. Use this action for flagging a document that users want to read
again.

Modify Field
Replaces or appends a single field value with a new text value you specify. This action replaces only text
values for documents in Edit mode. To replace a value with something other than text, use an @function
formula or LotusScript program. This action can modify the value of a hidden field, if you can specify
the field’s name.

The ″Append Value″ option does not work for rich text, number, or time fields or for fields that are not
available within documents already saved in the database. Also, ″Append Value″ is not available if a
database does not contain any documents (for example, a database template).

To include ″Append Value″ in databases without documents:


1. Create a place holder document containing the field.
2. Create the agent using the field from the place holder document.
3. Delete the document.

To specify a value:
1. Select the field to be modified from the Field pull-down list.
2. In the Value text box, enter the new value.
3. Select ″Replace value″ or ″Append value.″

Modify Fields by Form


Replaces several field values on a form with new text values you specify. This action replaces only text
values. To replace a value with something other than text, use an @function formula or LotusScript
program. This action marks processed documents as read.

To specify:
1. Select the form.
2. Enter the new value in the fields.

Chapter 10. Adding automation to applications 267


Move to Folder
Moves the highlighted document in a view or folder to a different folder. This action removes the
document from the source folder and adds it to the specified folder. The document is not deleted from
the database.

Remove from Folder


Removes selected documents from a folder you specify but does not delete the documents from the
database. If a document is included in several folders, this action removes the document from the
specified folder, but does not remove the document from other folders. If a document is included in only
one folder, this action removes the document from the folder and changes its category to Uncategorized.

Reply to Sender
Sends a reply to a mail memo automatically. Replies are not sent to a mail memo that was generated by
an agent. The Body field accepts only plain text. It does not accept styled text, graphics, or attachments.

To specify:
1. Select ″Reply to sender only″ or ″Reply to all.″
2. In the Body field, enter the reply text.
3. (Optional) Click ″Include copy of document″ to append the original message to your reply.
4. Select ″Reply only once per person″ if a person is included in multiple mailing groups.

Run Agent
Allows you to chain agents together with other agents or combine LotusScript programs, @function
formulas, and Java in one agent. The agent to be run must already exist in the database.

The documents that additional agents process are determined by the first agent. All subsequent agents
use the same documents, regardless of their own settings. The first agent completes its search and actions
first and then passes that information to the second agent. For example, Agent A searches for all
documents with the word ″green,″ replaces ″green″ with ″yellow,″ and then runs Agent B. Agent B
launches its own search queries and actions only on the documents that Agent A processed.

Send Document
Mails the current document to the recipients designated in the document’s SendTo field. This action
works like the @MailSend function. To predict the recipient, the document must have a SendTo field. If it
doesn’t, 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
doesn’t contain these fields, they default to normal priority, no delivery report, and no return receipt,
respectively.

Send Mail Message


Mails the selected document as a whole document or as a link. The Body field accepts only plain text. It
does not accept styled text, graphics, or attachments.

To specify:
1. Specify recipients in the To field.
2. (Optional) Click More to specify more addresses using text or formulas for the To:, cc:, bcc:, and
Subject: fields.
3. Enter a subject.

268 Application Development with Domino Designer 7


4. In the Body field, enter the message text.
5. (Optional) Click ″Include copy of document″ to append the document to the message.
6. Select ″Reply only once per person″ if a person is included in multiple mailing groups.

Send Newsletter Summary


Searches a database for documents matching conditions you specify, then sends a summary document
with links to the individual documents. The summary information includes items such as a one-line
description of the Date, Author, and Title columns.

The ″Gather at least″ option does not apply to sending a document summary from a view or folder with
an action because the action can act on only the highlighted document, and ″Gather at least″ acts on
multiple documents.

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

@Function Formula
Adds a customized @function formula.

Using LotusScript for automation


Use LotusScript(R) for shared and unshared actions, buttons, action hotspots, picture hotspots, script
libraries, events, and agents. LotusScript can be used to access data in Notes databases and in external
applications. For example, you can use LotusScript to change a value in one document based on values in
other documents or modify database ACL lists.

See the Domino Designer Programming Guide and the LotusScript Language Guide for more information
about LotusScript.

Working with HTML


You can use the LotusScript Print statement with HTML as follows:
v To display HTML information
For example, add this line to display the message ″Thank you for your submission″:
Print "<H1>Thank you for your submission</H1>"
v To provide instructions to a browser
For example, add this line to direct a browser to the Domino Web site:
Print "[http://domino.lotus.com]"

Restrictions for using the Print statement include:


v It must be attached to a user-run automated component, such as an action, a button, a manually-run
agent, or a WebQuerySave event that uses @Command([RunAgent]) or @Command([ToolsRunMacro]).
v If it is attached to a manually-run agent, it must also be a shared agent.
v It cannot be attached to a WebQueryOpen event.

Chapter 10. Adding automation to applications 269


Restricted LotusScript and Java agent operations
Note that restricted operations are available only to users with unrestricted access; restricted operations
are not available to users with restricted access.

The ability to use the LotusScript or Java backend class methods to create new or replica databases is
controlled by the ″Create New Databases″ and ″Create Replica Databases″ fields in the Server document
in the Domino Directory.

Classes and methods in this table also apply to remote Java/JavaScript programs that access server based
Domino objects over CORBA/IIOP. User access is controlled by the server document fields ″Run
Restricted Java/Javascript″ and ″Run UnRestricted Java/Javascript″ found under the heading ″IIOP
Restrictions.″

Table of restricted backend class and method


Task LotusScript Java
Using a disk-based NotesLog OpenFileLog(path) Log openFileLog(path)
log file
Using Environment NotesSession GetEnvironmentString() Session getEnvironmentString()
variables
NotesSession SetEnvironmentVar() Session SetEnvironmentVar()

NotesSession Session GetEnvironmentValue(SystemVariable,


GetEnvironmentValue(SystemVariable, true) true)
Encrypting or NotesDocument Sign() Document sign()
signing
NotesDocument Encrypt() Document encrypt()
Embedded Object NotesRichTextItem EmbedObject() RichTextItem embedObject()
manipulation
NotesEmbeddedObject ExtractFile(path) EmbeddedObject extractFile(path)

270 Application Development with Domino Designer 7


Table of restricted programming language operations
Task LotusScript statement Java
File I/O Chdir No file I/O operations allowed

Chdrive

close

curdir

dir

eof

fileattr

filedatetime

filelen

freefile

get

getfileattr

input

input #

inputb

line input #

loc

lock s

lof

mkdir

Open

reset

rmdir

seek

setfileattr

unlock

width

write
Network I/O N/A No network I/O operations allowed
Setting system date/time Date and Date$ Time and Time$ N/A

Chapter 10. Adding automation to applications 271


Task LotusScript statement Java
Calling a ″C″ routine External C calls Declare Users with unrestricted access must also
set the NOTES.INI parameter
″JavaUserClasses″ to the file name of the
class file that contains the native methods.
For example, use JavaUserClasses=
c:\lotus\notes\MyJavaClasses. This
overrides a security restriction of the
Agent class loader, which does not allow
classes with native methods to be loaded.
Executing another application ActivateApp Not allowed

Shell

Formulas for automation


Use formulas for shared and unshared actions, buttons, formula pop-ups, hotspots, events, specific
infoboxes, and agents.

Using @command formulas with actions and hotspots


When an action or hotspot uses an @command formula, the formula works only when it runs in the
appropriate context. Keep the following in mind:
v A hotspot or action can process a field or an entire document, but not a selected area. When you point
to the button to activate it, you lose the previous selection -- that is, the previous highlight disappears,
and only the button is highlighted. To work around this, use the @command with parameters such as
EditLeft or EditRight which move the focus within a document. Then when the user activates the
hotspot or action, Notes uses the formula to determine what is affected.
v Formulas designed to edit a field don’t work when the document is in Read mode. To work around
this, use the @command([EditDocument]) to put a document in Edit mode.

Security features that affect automation formulas


Automated components with formulas run by users work only if users activate them in the correct
context and have enough privileges to perform the automated task. For example, if a formula in a
hotspot uses @SetField to change a field value, the hotspot doesn’t work when the user activating it has
only Reader access or the document is in read mode.

An automated component with formulas cannot usually complete unauthorized tasks on a database
stored on a server because most users do not have privileges that allow them to run such tasks. However,
in a local database where you have Manager privileges by default, an automated component with a
formula could potentially change documents. If you are unfamiliar with the formulas associated with an
automated component, review them first.

If the user’s NOTES.INI file includes this statement


NoExternalApps=1

then any formula involving the following features is disabled:


v @command
v @PostedCommand
v @DbCommand, @DbColumn, @DbLookup (only if it refers to a non–Notes database)
v @MailSend
v Dynamic Data Exchange (DDE) including all @DDE functions
v Object Linking and Embedding (OLE)

272 Application Development with Domino Designer 7


v Launching attached files

The user doesn’t see a message, but the formula won’t run.

JavaScript for automation


Use JavaScript for shared and unshared actions, buttons, action hotspots, picture hotspots, script libraries,
and events. JavaScript Version 1.3 is currently supported.

JavaScript is particularly useful for providing interactive components, such as:


v Form and field validation
v Mouse effects (such as image rollover buttons and friendlier URLs)
v Numeric calculations
v Dialog box simulations

If you have selected JavaScript, you can write code that executes in either the Notes client or on the Web.
If you have selected Common JavaScript, you can write code that executes in both the Notes client and
on the Web.

When you use JavaScript, more processing can be done at the workstation instead of the server, thereby
reducing network traffic and improving run-time task processing.

JavaScript works with Notes objects, such as windows, documents, or fields. The objects that you can
attach to JavaScript vary, according to the component you are working on. In the Info List, click Objects
to see what is available. For example, set up a JavaScript automated task for an OnClick event in a
hotspot.

You can also check the following table to see what JavaScript objects are available in each automated
component and whether they are supported in different browsers and the Notes client.

Table of supported JavaScript objects for automated components


This table lists the JavaScript objects that are available for automated components and which browsers
support the event. This table assumes you are running Internet Explorer 5.0 or later, or Netscape
Navigator 4.73 or later.

Action Shared Action Shared Action -


JavaScript Object Button Hotspot Form Action - Form View Action View
onBlur
Works in Internet IE IE IE IE IE
Explorer (IE),
Netscape
onClick
Works in Notes Notes Notes Notes browser, Notes browser, Notes browser,
browser, browser, browser, Notes client, Notes client, Notes client,
Notes client, Notes client, Notes client, Netscape, IE Netscape, IE Netscape, IE
Netscape, IE Netscape, IE Netscape, IE
onDblClick
Works in Netscape, IE Notes client, Netscape, IE Netscape, IE Netscape, IE Netscape, IE
Netscape, IE
onFocus
Works in IE, Netscape IE IE IE IE IE

Chapter 10. Adding automation to applications 273


Action Shared Action Shared Action -
JavaScript Object Button Hotspot Form Action - Form View Action View
onHelp
Works in IE IE IE IE IE IE
onKeyDown
Works in IE IE IE IE IE IE
onKeyPress
Works in IE IE IE IE IE IE
onKeyUp
Works in IE IE IE IE IE IE
onMouseDown
Works in Netscape, IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE
onMouseMove
Works in IE IE IE IE IE IE
onMouseOut
Works in IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE
onMouseOver
Works in IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE
onMouseUp
Works in Netscape, IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE Netscape, IE

Actions and agents names


The names you give to manually-run agents appear as choices in the Actions menu. The names you give
to form actions and view actions appear as choices in the Actions menu and on the action bar. The names
are case sensitive and can be any combination of characters, including letters, numbers, spaces, and
punctuation.

Naming tips
v Choose short names for form and view actions that you design to appear as action bar buttons.
v Choices on the Actions menu appear in alphabetical order. To force names to appear in a different
order, number or letter them.
v Use consistent names across databases to enable users to recognize identical agents and actions.

Naming techniques
Aliases
You can use an alias with agents. An alias is another name, or synonym, for a particular 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.

To create an alias, add a vertical bar (|) symbol and the alias name to the right of the original name.
Always keep the original name as the leftmost name.
Agent1 | Agent1_Alias
You can have more than one alias. Separate each with the vertical bar (|) symbol.

274 Application Development with Domino Designer 7


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.

Hiding automated components


When you create most automated components, you can hide them under varying conditions. Use the
Hide When tab located on many Properties boxes to specify when to hide it.
v Hide from Notes R4.6 or later
Hides a component when it is viewed from a Notes workstation. This is useful for hiding components
such as action bar buttons that you provide to Web users as substitutes for Notes menu choices.
v Hide from Web browsers
Hides a component when it is viewed from a Web browser. This is useful for hiding components that
aren’t relevant to Web users.
v Hide from Mobile
Hides a component when it is viewed by a mobile user.
v Hide when opened for reading; Hide when previewed for reading
Hides a component when a document is opened in Read mode. These options are useful for
components that are relevant only to new documents or documents in Edit mode -- for example,
actions that modify a field.
v Hide when previewed for editing; Hide when opened for editing
Hides a component when a document is opened in Edit mode. These are useful for components that
are relevant only to completed documents -- for example, moving documents to another database,
creating response documents, or marking documents as unread.
v Hide when printed
Hides the component when users print a document. This is useful for removing clutter from a printed
document.
v Hide when copied to the clipboard
Hides the contents of the component when users copy a document.

Note: If you create or save a document from a form that contains a field with ″Hide when copied to
the clipboard″ checked and then copy the contents of the document somewhere else, the contents of
that field will not be pasted.
v Hide if formula is true
Hides the component under certain conditions -- for example, based on user name or access level in
the access control list. For example, the following formula hides the component from all users except
Barbara Meehan:
@If(@Name([CN];@UserName) !="Barbara Meehan";@True;@False)

Chapter 10. Adding automation to applications 275


276 Application Development with Domino Designer 7
Chapter 11. Developing applications using third-party tools
and WebDAV
As you are developing an application, you may want to supplement the tools provided with Designer
with tools of your own choosing. For example, you may have a favorite graphics editor you use to design
images for your application, or you may have a favorite HTML editor that you want to use to design
pages. You launch and use third-party tools from within Designer.

For information on adding third-party tools to the tools menu, see the topic ″Customizing the Designer
Tools menu″ in this chapter.

The Domino web server also supports Web-based Distributed Authoring and Versioning (WebDAV) so
that you or others on your team can edit and manage parts of a database using WebDAV-enabled clients.

Designers with the proper access to a Domino database can open files from a WebDAV client -- such
Macromedia Dreamweaver -- edit the files, and save them back to the database.

For information on using WebDAV, see ″Editing and managing database resources using a WebDAV
client.″

Customizing the Designer Tools menu


You can customize the Tools menu in Designer to include menu items that launch other applications or
your own custom formulas. For example, you might want to include a menu item to launch your favorite
image editor while you are in the list of images, or you might want to add a formula that you can launch
at any time that automates your design process. When you add a tool, you can specify when you want
the tool available. You might need some tools for every phase of your design work, and other tools for
use with very specific design activities, such as designing a page or a frameset. In this way, you can
personalize your application development process throughout your Designer desktop.

To add a tool
1. Select Tools - Add Tool.
2. Enter the name of the tool.

Tip: To make the tool accessible to users with physical disabilities, specify a keyboard accelerator key
for the tool name by putting an underscore (_) before the letter you wish to use as the accelerator key.
3. Do one of the following:
v Select ″Run program″ to have a menu item launch a tool from within Designer. Enter the path for
the executable file or browse to select the executable.
v Select ″Run formula″ to launch a tool using an @commmand formula.
4. In the Tool Location section, specify one or more contexts when the tool should be available. That is,
if you do not want the tool to be always available, choose the design elements where you might use
the tool in your design work. For example, if you select Form Design, the tool will be available
during form design; if you select Form list, the tool will be available from the tool menu when you
are in the list of forms.
5. Click OK.
The name of the tool appears on the Tools menu for the contexts. That is, if you specified the tool
should always be available, it will always be on the Tools menu. If you specified the tool should only
be available for page design, it will only display when a page has focus in the work pane.

277
Organizing tools on the Tools menu
After you have added tools to the Tools menu, you can edit the tool names or their associated formulas,
delete one or more tools, organize tools into submenu groupings, or change the context for a tool.

To add a submenu for tools


1. Select Tools - Customize Tools.
2. Select a design context and click ″Add Submenu″ to add a submenu for that context.
3. Enter a name for the submenu and click OK.

Tip: To make the submenu accessible to users with physical disabilities, specify a keyboard
accelerator key for the submenu name by putting an underscore (_) before the letter you wish to use
as the accelerator key.
4. Use drag and drop or the Copy and Paste buttons to move tools to the submenu.

To move a tool to another design context


1. Select Tools - Customize Tools. Click the arrow next to a design context to display the tools associated
with that context.
2. Select one or more tools.
3. Drag and drop the tools to a new context.

To copy, paste, or delete a tool:


1. Select Tools - Customize Tools. A dialog box displays the list of design contexts.
2. Click the arrow next to a context name to display the tools associated with a design context.
3. Select the tool name.
4. Click Copy to copy the tool to the clipboard.
5. Select the design context where you want to place the tool and click Paste.
6. Select a tool and click Cut to remove the tool from its original context.

To edit a tool
1. Select Tools - Customize Tools.
2. Click the arrow next to the name of a design context to display tools associated with that design
context.
3. Select the tool name and click Edit. You can edit the name of the tool and/or the formula that it
executes. Note that if you had chosen to run an executable program from the menu, the action is
represented as an @command([Execute]) formula. You can change the name of the executable file or
customize the formula.
4. Click OK to confirm your changes.

Editing and managing database resources using a WebDAV client


The Domino Web server supports Web-based Distributed Authoring and Versioning (WebDAV), a
technology that allows users with Designer access to a database to edit or move items in the design
collection of a database without using a Designer client. For example, you may build a page using a
favorite HTML editor. Using Windows Explorer, you can drag that page into an NSF file for inclusion in
a Domino application. Similarly, an application designer collaborating on a project might open an HTML
page using the Internet Explorer 5.x, edit the page, and then place the page back into the database.
WebDAV technology gives you much greater flexibility in the development process as you can use
third-party tools and contribute to application design from remote Web clients.

278 Application Development with Domino Designer 7


The types of Domino database resources you can access with a WebDAV client are:
v File resources
v Images
v Cascading Style Sheets (CSS)

Setting up WebDAV
Before you use WebDAV, it must be enabled on the Domino server. Check with your system
administrator to make sure WebDAV is enabled in the Web Site document (found under the Internet Sites
view in the Domino Directory).

You must also do the following:


v Provide the user with either Designer or Manager access in the database Access Control List (ACL).
The user also must have both ″Create documents″ and ″Delete documents″ privileges enabled in the
database ACL.
v On the Advanced tab of the database ACL, set the ″The maximum Internet name & password″ field to
either Designer or Manager access.
v Ensure that you have the correct proxy settings configured for the WebDAV client.

Note: If your WebDAV client uses a proxy server to access the Domino server where the WebDAV
database resides, you may experience problems when you try to connect to the WebDAV database. If
so, disable the proxy for access to that server. You can selectively disable the proxy, specifying that the
proxy not be used for access to that one particular server. If you are using Microsoft Windows
Explorer, Internet Explorer 5, or Internet Explorer 6 as the WebDAV client, open the browser and go to
Tools - Internet Options - Connections tab. Choose LAN settings, then click the Advanced button. In
the Exceptions edit box, enter the hostname of the Domino WebDAV server, such as
develop1.acme.com.
v Check with your server administrator to make sure sessions authentication is disabled in the Web Site
document (found under the Internet Sites view of the Domino Directory) that enables WebDAV.

For more information on setting up the Domino server to use WebDAV, see Administering the Domino
System.

Enabling design locking


Design locking prevents the situation where one collaborator overwrites the work of another when
working on the same resource. Some WebDAV clients (such as MS Word 2000, Excel 2000, and
Dreamweaver 4.x) will lock the file when it is opened for edits or when the file is saved to a WebDAV
server. In order for these clients to work with WebDAV databases on the Domino server, you must enable
″Design locking″ for each of the WebDAV databases. To turn on design locking for use with WebDAV,
enable ″Design Locking″ on the Designer tab of the Database Properties box.

For more information on design locking, see the chapter ″Completing an Application and Managing
Design Changes.″

In order for design locking to work, the Administration server for the database must be accessible. The
Administration server (also known as the Master Lock server) is usually the server on which the database
was created, unless an alternate server is explicitly specified on the Advanced page in the Access Control
List for the database. Since many applications that use locking do so without explicit action by the user,
check that the Administration server for the database is correct and that the server is accessible, and
ensure that design locking is enabled to prevent problems with WebDAV.

Notes about working with WebDAV


The following are tips for using WebDAV with an NSF file.

Chapter 11. Developing applications using third-party tools and WebDAV 279
v If a database has the field ″Don’t allow URL open″ enabled in the Database Properties box, then you
will not be able to access the database using a WebDAV client.
v Macromedia Dreamweaver 4.01 is required to use WebDAV to access databases on a Domino server.
This upgrade can be downloaded from Macromedia’s web site at:
http://www.macromedia.com/support/dreamweaver/downloads/dw4_updater.html
v In order for Dreamweaver locks (Check In and Check Out) and Designer client locks to interoperate
correctly, the following must be configured.
In Dreamweaver, under the Remote Sites configuration panel, the user needs to supply a user name to
authenticate -- for example, James Smith/Acme -- and a valid password.
The user must also supply an e-mail address -- for example, james_smith@acme.com. This e-mail
address is what is used for Check In/Out in Dreamweaver. The email address specified in
Dreamweaver must exactly match the e-mail address that is in the ″Internet Address″ field in the
Person document in the Domino Directory (names.nsf) for the user James Smith/Acme. Only then will
both clients recognize the user to be the same person.

Limitations
v Microsoft’s Front Page 2000 is not a supported WebDAV client for use with Lotus Notes Domino.
v WebDAV-enabled clients on MAC PCs are not supported with the Lotus Notes Domino Web Server.
v The following are WebDAV-enabled clients that should work correctly with WebDAV on a Domino
server: Microsoft Internet Explorer 5.0x or greater, Windows Explorer on NT, Windows XP, Windows
98, Windows 2000 Macromedia’s Dreamweaver 4.01, Microsoft Word 2000 and Excel 2000.

Note: Microsoft uses the term ″Web Folders″ to represent their WebDAV client application. Please refer to
Microsoft’s documentation for how to use ″Web Folders.″

Note: With Macromedia’s Dreamweaver you configure a ″Remote Site″ to use WebDAV in order to access
Domino databases via WebDAV. Please refer to Dreamweaver’s documentation for more information on
how to configure this.

Accessing database resources using a WebDAV client


WebDAV uses a containment hierarchy -- much like a file system directory -- to organize files into groups
called collections. A collection can contain other collections and/or files. In Domino, this hierarchy is
represented using the name of each design element (the value stored in the $TITLE field for each
element) as the file name. For example, a graphic resource named images/logo.gif would appear in a
WebDAV collection as a file named logo.gif in the root collection named images. In the Designer client,
collection elements appear in the Shared File Resources design list with a trailing slash appended to the
name in the $TITLE field and an optional comment. Collection elements are file resource design elements
with the additional design flag ’/’ in the $Flags field.

Virtual collections
When a design element is inserted into a Domino database via WebDAV, Domino creates collection
elements to represent all of the collections in the containment hierarchy of the files inserted. These
collection elements hold properties for the collection and represent collections that may be, or might later
become, empty (that is, have no contained elements). A collection can exist, however, without a collection
element to represent it. This can happen when elements are created or renamed using the Designer client.
In this case, the collection is referred to as a virtual collection. A virtual collection exists when a design
element specifies the name of a collection in its path name, but a collection element for the collection
does not exist. For example, if the design collection for a database contains an image resource titled
images/logo.gif, but does not contain a collection element named images, then images is a virtual
collection.

Virtual collections behave much like non-virtual collections with the following exceptions:

280 Application Development with Domino Designer 7


v The properties of a virtual collection are a set of defaults based on the properties of the database. For
example, the creation date of a virtual collection is the creation date of the database.
v A virtual collection that no longer contains elements disappears.
v If a WebDAV client attempts to set properties on a virtual collection, the Domino server attempts to
create a collection element for the collection, transforming the virtual collection to an actual one.

Accessing database elements


When using a WebDAV client to access a database, you start by creating a connection from the client to a
database on a specified server. For example, in Windows Explorer for windows 2000, you create a
Network Place. To identify the database, you enter a URL that specifies the hostname of the Web site, the
database name, and append the string $files to the end of the path to indicate to the server that this is a
WebDAV request. For example, to open the database named sales.nsf as a Web folder from Windows
Explorer, you enter the path as follows:
http://servername/sales.nsf$files

Once you have mapped a database to a WebDAV client, you can use the interface of the WebDAV client
to browse the database and select elements within the database to open.

To display the contents of a resource within a database from a Web browser using a URL, you append
the name of the resource (the value of the associated $TITLE field) to the folder name. For example,
http://servername/sales.nsf$files/images/logo.gif

Note: You cannot use Microsoft’s Internet Explorer to access a WebDAV database that is located in a
subdirectory of the Domino server’s data directory. Use Windows Explorer instead.

Once you have established a connection to a Domino database using a WebDAV client, you can open a
resource, edit it, and save it back to the database. Or you can add an element that you have created using
a third-party editor to the database.

CAUTION:
WebDAV clients do not maintain operating system attributes, such as a read-only state. For example, if
you create a HTML page, and flag it as being a ″read-only″ file in Windows, the page will not be
flagged as read-only if you add it to a database and view it from Designer.

Avoiding and resolving naming conflicts


WebDAV requires a unique name for each resource. Because a Domino database can contain more than
one element with the same value in the $TITLE field, naming conflicts can sometimes occur. For example,
a naming conflict can happen if two authors are working on different replicas of the same database and
they both create a new element with the same name. When the databases are replicated, each replica will
contain two different design elements with the same $TITLE value.

Note: Design locking does not prevent naming conflicts because in Domino locking is based on the
noteID, not the name of a note.

Domino deals with naming conflicts by dynamically adorning the names of conflicting elements with the
NoteID of the element using the form ″Name(NoteID).ext.″ The server uses this form to uniquely identify
each element involved in a name collision, but does not actually rename the elements in the database. If
you see this naming convention using a WebDAV client, try to resolve the conflict to avoid problems. You
can use Windows Explorer or any other WebDAV client to rename one or more of the conflicting
resources. When the name collision is resolved in this way, the other affected resource name reverts back
to the unadorned form of the name in $TITLE. You may need to refresh the view of a WebDAV client in
order to see the changes. You can also change the name of an element in the Designer client.

Chapter 11. Developing applications using third-party tools and WebDAV 281
When a name collision involves a collection element, the collection element name is adorned as described
above. However, if the collection contains any elements, then an unadorned virtual collection will be used
to hold the contents of the collection. The result is that when viewed from a WebDAV client, there will be
both a name-adorned collection which contains no elements, and an unadorned collection which contains
all of the elements in the collection. Collections with adorned names cannot be the target of a move or
copy operation and you cannot create elements in collections with adorned names -- that is, they will
always be empty. You can, however, rename or delete a collection with an adorned name in order to
attempt to resolve the name collision. Deleting a collection with an adorned name only deletes the
collection element that is involved in the name conflict. It does not delete any of the elements that are
contained in the virtual collection with the unadorned name.

Note: The above discussion implies that names that match the adorned name style (″Name(NoteID).ext)″,
where NoteID is the ASCII representation of an eight-digit hexadecimal number, should be avoided in
design element names. While the Domino server will not allow you to create or name a design element
from a WebDAV client with a name that could be confused with an adorned name, the Designer client
will allow you to do this.

Using WebDAV in a replicated environment


When WebDAV is used to modify the design of a database in a replicated environment, you should
enable design note locking on the replicated databases and use WebDAV-enabled applications that
support locking. Locking ensures that any changes are replicated to the master lock database on the
administration server whenever a design element is locked or unlocked, and that other applications are
not allowed to modify a design element while it is locked. For WebDAV clients that do not support
locking (such as Windows Explorer), the Domino Web Server will lock design elements on the client’s
behalf prior to making any updates, then unlock the design element after the update is complete. In
addition, methods that return information about an unlocked design element on a database that has
design note locking enabled (for example -- GET, HEAD, and PROPFIND) will replicate the design note
with the master lock database if necessary before returning any data. This minimizes the chances of lost
updates or replication conflicts when using WebDAV clients that do not support locking.

The down side of the protection provided by locking this is:


v The administration server (also known as the ″Master Lock″ server) for the database must be available
in order to do anything with WebDAV if design note locking is enabled. The administration server is
specified on the Advanced panel of the database access control list.
v Performance is significantly impacted for replicas that are not on the administration server. If you need
to use a WebDAV client that does not support locking to perform operations on a large number of files
(for example, using Windows Explorer to copy a collection of files into a database), you may want to
temporarily disable design note locking, or set the administration server for the database to be the
server on which the database resides, prior to performing the operation. When you have completed the
operation, you can restore the original settings and then replicate the database with the master lock
database and deal with any replication conflicts. Depending on the number of elements involved, this
can be much more efficient than the multiple single note replications that the Domino server would be
required to do otherwise.

282 Application Development with Domino Designer 7


Chapter 12. Connecting to enterprise data
Incorporating back-end data into everyday business processes maximizes the value of a Designer
application. Designer includes a range of technologies for the security and control of business processes,
forms routing, and approvals management. With enterprise integration technologies, you can incorporate
traditionally difficult-to-reach data into your business applications.

Using data integration tools and services, you can create applications that contain connectors to relational
databases (such as Oracle and DB2), Enterprise Resource Planning systems (such as SAP, PeopleSoft, and
J.D. Edwards), and transaction systems (such as CICS, IBM MQSeries®, and IMS). You can accomplish
this either programmatically or with visual tools that work with native database drivers.

The following connection solutions are available either as part of Domino Designer or as add-on tools:
v Data Connection Resource (DCR)
v @DB commands
v Domino Enterprise Connection Services (DECS)
v LotusScript and Java classes
v Domino Connectors
v Lotus Enterprise Integrator (LEI)

Data Connection Resource (DCR)


A Data Connection Resource is a design element you define within Designer to establish a data exchange
between a Domino application and an external data source. Like other design resources, you can define a
DCR and then use it in many places within an application, or use it in another application. For example,
you might establish a connection to an inventory catalog stored as a table in a Microsoft Access database.
You could then use that connection in a variety of forms in your application, or in several related
applications.

DCRs provide a convenient alternative to using the DECS Administrator that ships with the Domino
server.

@DB commands
As in previous releases, you can use @DB commands and the LotusScript Data Object (LS:DO) to
exchange data with relational databases using ODBC.

For more information on @DB commands and LS:DO, see the Programming Guide.

Domino Enterprise Connection Services (DECS)


Domino Enterprise Connection Services (DECS) is a visual tool and high performance server environment
you can use to create Web applications that provide live, native access to enterprise data and
applications. The visual tool includes an application wizard and online Help to assist you to define
external data source connections -- for example, DB2, Oracle, Sybase, File directory, EDA/SQL, or ODBC
-- and fields within your application that automatically contain external connector data.

For more information on connecting to legacy databases, see the Domino Enterprise Connection Services
User’s Guide.

283
LotusScript and Java classes
LotusScript and Java include classes for enterprise data access. Use these classes to customize applications
to incorporate information from relational databases, transaction systems, and enterprise resource
planning (ERP) applications according to your business needs. The Domino Server includes the Lotus
Domino Connector LotusScript extension (LSX), permitting programmatic access to Domino Connectors
from LotusScript.

For more information about the Domino Connector LSX, see the LotusScript Extension for Domino
Connectors Reference Guide.

The Domino driver for JDBC, providing standard JDBC access to data in Domino databases, is also
available from the Lotus Web site at http://www.lotus.com. Using this driver, you can write Java applets
and applications that use JDBC to access information in Domino databases. JDBC classes now ship with
Domino in the java.sql classes. These classes may be used when writing Java agents to access relational
data via standard JDBC drivers.

For more information on LotusScript and Java classes, see the Programming Guide.

Domino Connectors
Domino Connectors are modules that provide native connectivity to external, relational databases. You
can access these connectors through the forms-based development tool in DECS, or through the Domino
object classes using LotusScript or Java languages.

Additionally, Lotus supplies connectors for ERP systems. These are sold separately. For information about
these connectors, visit the IBM Web site, http://www.ibm.com.

For more information on Domino Connectors, see the Domino Connectors Setup Guide.

Lotus Enterprise Integrator


Lotus Enterprise Integrator(TM), a module previously called Lotus NotesPump, extends DECS
functionality beyond real-time data sources to include support for high volume data transfer and
synchronization. Lotus Enterprise Integrator provides visual tools to manage integration between data
sources without programming, including the capability to initiate event-driven or scheduled high volume
data transfers between Domino applications and relational databases and other enterprise applications.
Lotus Enterprise Integrator also supports programmatic data transfers using LotusScript and Java Classes.

For more information on Lotus Enterprise Integrator, see the Lotus Web site at http://www.lotus.com.

Table of connectivity solutions


This table describes some of the connectivity solutions available to you.

Connectivity solutions Description Domino version


DCR - Database Connection Design element within Designer that lets you define R6 or higher
Resource a connection to a database for use in a form or
field.
DECS - IBM Lotus Domino Forms-based development tool. Provides live access R4.6 or higher
Enterprise Connection Services to enterprise data and applications, including
relational databases, transaction systems, and
Enterprise Resource Planning (ERP) systems.
LS:DO - LotusScript Data Object Provides LotusScript access to any ODBC-compliant R4.0 or higher
data sources.

284 Application Development with Domino Designer 7


Connectivity solutions Description Domino version
JDBC - Java Database Provides access from Java agents to relational data R4.6 or higher
Connectivity via standard JDBC classes. A JDBC to ODBC bridge
also ships as a part of Domino.
Lotus Domino Connector Unified object model with a consistent interface to R4.6.3 or higher
LotusScript Classes programmatically access enterprise data and
applications. These classes can be used with
LotusScript or Java.
Lotus Domino Connectors Modules which provide native connectivity to R4.6.3 or higher
enterprise data sources. These connectors can be
accessed through Domino Enterprise Connection
Services or programmatically through Domino
classes.

Connectors to DB2, Oracle, Sybase, Text & File


based systems, EDA/SQL, and ODBC are provided
with the Domino server. Premium connectors to
ERP applications, Transaction Monitors, and
Directory systems are available separately.

Note that the NotesSQL® driver for ODBC access to


Domino data is available for free from the Lotus
Web site at http://www.lotus.com.
LSX - LotusScript extensions Create custom objects that work natively with R4.0 or higher
Domino applications as well as Java and OLE.
Some examples of LSXs are MQSeries, SAP, DB2,
and rich text.

The DB2 LSX provides classes for programming


directly to the DB2 client access library.
IBM Lotus Enterprise Integrator Data distribution server that provides support for R4.0 or higher
event-driven or scheduled high-volume transfer and
(Lotus Notes Pump) data source synchronization.
IBM Lotus Domino Connector Provides developers with tools and information to R4.0 or higher
Toolkit build additional Domino Connectors and Java or
LotusScript classes.

Overview of Data Connection Resources


Data Connection Resources (DCRs) bring the technology of Domino Enterprise Connector Services
(DECS) into Designer so that you can define a connection to an external data source, such as a relational
database, and use the connection to link the fields in a form to fields in the external source. DCRs are
reusable in an application and can be shared across applications. You can use DCR technology to access
data in enterprise systems and then take advantage of the power of a Domino application to replicate,
share, secure, and manage the data.

To create an external connection, you first need to install the DECS server software on your Domino
server. The client software for the application you are connecting to -- such as DB2 or ODBC -- must also
be installed on the Domino server. You can develop an application locally, but you will be unable to
browse the external metadata when designing your application.

Overview of creating a DCR


To establish a connection with an external resources, follow these steps, described in detail in the topics
that follow.
1. Create a data source resource on the server that maps to the external database you plan to access.

Chapter 12. Connecting to enterprise data 285


2. Create the DCR by identifying the type of application you are connecting to and specifying the
existing data source.
3. (Optional) Customize the DCR settings.
4. Set a database property that allows for connection to external data sources.
5. Create fields on a form that map to fields in the external data application using one or more DCRs.
6. Import external records to bring the existing data from an external database into a Notes application.

Establishing a data source resource for use with a DCR


Before you can create and use a Data Connection Resource, you must first create a data source server
reference to the external application using a data source that is defined on the server. For example, to
create a data source for a Microsoft Access database on a Windows NT server, you would use the
Windows System Tools utility to specify the Microsoft Access table as a data source and ODBC as the
data driver to use for data exchange.

If you do not have access to the server on which the external database resides, work with your system
administrator or database manager to make sure the data source is defined.

Creating a database connection resource


A data connection resource (DCR) is a reusable connection between a Domino application and a
non-Domino database. You must have a defined data source on the server before you can create a DCR.

To create a DCR
1. Launch Domino Designer.
2. In the Design pane, select Shared Resources - Data Connections.
Any existing data connections display in the Work pane on the right.
3. Click the ″New Data Connection″ button at the top of the Work pane. The Data connection
Properties box appears.
4. Enter a name for the connection resource.
5. (Optional) Enter an alias to use in place of the name.
6. (Optional) Enter a comment describing the connection.
7. Select the class of application you are connecting to -- that is, the type of database.
8. Select the type of connection. Certain databases, such as DB2 and Oracle, have native drivers that are
listed as an available type of connection. If a specific driver is not available, choose a generic one,
such as ODBC or OLE DB. For example, to access an MS Access database, choose OLE DB as the
connection type.
9. Enter the username and password you use to access the system you are connecting to.
10. Enter the name of the data source that maps to the external application you plan to access.
Depending on the type of database you are connecting to, you may have to supply specific
connectivity information such as aserver name, a host string, or a catalog.
11. Select the type of object to connect to: table, view, or procedure.
12. Enter the User ID for the owner of the table or view. The owner is the creator of the database you
are connecting to. The owner must supply you with the correct owner ID, which is typically in the
format ownername.tablename. In the case of a procedure, you must also enter the procedure name for
any of the document events that will trigger the procedure.
13. Enter the name of the table, view, or procedure. You can click the ″Browse Metadata″ button to
browse the external database for the name of the table, view, or procedure.
14. (Optional) Click the Options tab to customize the settings for the DCR.

286 Application Development with Domino Designer 7


Specifying options for the data connection resource
Once you have defined the basics of the data connection resource, you can customize the resource with
some optional information. The following options are available on the Options tab of the Data
Connection Resource Properties box and apply to all types of data connections.

To open the Data Connection Resource properties box, choose Design - Design Properties.

Maximum number of concurrent connections


Set the maximum number of concurrent connections for the data connection. The default is one.

Block key field updates


This option is checked by default to prevent the value of a key field from changing. Key fields are used
in back-end lookups.

Only update changed fields


This option prevents any updates to fields in the external data source unless the corresponding fields in
the Notes document have been edited.

Use this option if you have triggers in the external system that monitor updates to individual columns of
a table.

Enable conflict detection


This option ensures that the external data has not changed since the Notes document was opened. If it
has changed, an update to the external data source will fail.

If this option is enabled and if you make changes to data in a Notes document and then save the
document, you must exit the document before making any more changes -- even though you have saved
the document.

Note When using an HTTP Server to access documents, ″Conflict Detection″ is not supported.

Space trimming
Specify whether to trim trailing spaces only on non-key fields or not at all.

Action on data mismatch


Specify what should happen when an error occurs. You can choose to return the error information, allow
for a loss of precision, or allow for data to be truncated. The option you choose depends on the type of
data being transmitted. For example, you might be willing to accept a loss of precision on numeric data
in cases where your source application supports a higher degree of precision than the target Notes field.
If you are dealing with long text strings, you might choose to truncate data where the two fields allow
for different string lengths. Note that choosing data truncation might result in a loss of precision for
numeric data. In cases where the complete integrity of the data is essential, you would opt for returning
the error information. Note that data truncation is never an option for key fields, as that would prevent
the application from working successfully.

Action on missing record


When a record you request is missing, you can set this option to return the error message, ignore the
error and continue the data retrieval, or create an external record. For example, if the external table
somehow gets out of synchronization and the DB2 row corresponding to a document is missing, this
option would create the external record in DB2, allowing the document stub to still be used. Otherwise,
an error message is returned, and the stub document cannot be opened or used.

Chapter 12. Connecting to enterprise data 287


Custom settings for specific applications
In addition to the general options listed above, some applications have additional custom settings.

Application Setting Usage


DB2 Data journaling Select this option to enable SQL querying for a non-journaled data source.
When the data source is non-journaled data -- for example, an IBM eServer
iSeries database without journaling -- SQL queries are not supported unless
this option is selected. This option sets the access mode to read only
(transaction isolation level of uncommitted read), which enables SQL queries.
The default access level is read-write (transaction isolation level of
committed read).
ODBC Single threading Some ODBC drivers do not support multithreaded execution. When using
such drivers, setting the Single Threaded option will protect the driver from
multithreaded execution. Intersolv ODBC drivers release 3.01 and above are
multithreaded. If erratic or unexplained behavior occurs, particularly at
times of high application traffic, set this option to single threading and
restart the activity.
OLE DB Provider The programmatic ID for the OLE DB provider to use.
OLE DB Provider string The required provider string values. This field

maps to the OLE DB DBPROP_INIT_PROVIDERSTRING property.


OLE DB Authentication The name of any authentication server used by the provider. This field maps
service to the OLEDBDBPROP_AUTH_INTEGRATED property.

Enabling connections to external databases


In order to establish a connection to an external data source, you must first enable external connections
for the database. Once that database property is set, you can then use your data connection resource
(DCR) in a form to exchange data with an external database.
1. Open the database where you plan to use a data connection and choose File - Database - Properties.
2. Click the Database Basics tab.
3. Select ″Allow connections to external databases using DCRs.″ This property is disabled until you have
created at least one DCR in the database.

Note: You may want to disable this while you are designing an application, and enable it when you
are ready to deploy your application. You must also disable this option when you import existing
records from an external database into your application.
4. Close and reopen the database to enable the property.

Using a data connection resource on a form


In order to establish a connection to an external data source, you must first enable external connections
for the database. Then you define a data connection resource (DCR). To use this resource to establish a
link between Notes and an external application, you use the DCR in a form. You define fields on the
form that map to the data you are retrieving from the external application. When you define a field, you
mark it as an external data source and associate it with the DCR.

To specify a default data connection for a form


If you are planning to use a DCR in more than one field on a form, you can specify a default data
connection, and, optionally, a default metadata object such as a table or view. When you create a field for
use with an external data source, the default information for the data connection is supplied
automatically. You can overwrite the default DCR with a different DCR if you wish.
1. Create or open a form.
288 Application Development with Domino Designer 7
2. Choose Design - Form Properties to display the properties box.
3. Click the Defaults tab.
4. In the ″Data Source Options″ section, you can browse for a data connection resource or enter the
name in the ″Default Data Connection″ field.
5. (Optional) Specify a ″Default metadata object,″ such as a table or view name, from the external
application.

To create fields for connecting with external data


1. Select the field you want to associate with an external data source.
2. Choose Design - Field Properties to display the Field Properties box.
3. Click the Info tab and select ″External data source.″
If you have specified a default DCR for the form, the information is applied to the field.
4. In the ″Data Source Options″ section, browse for or enter the name for the metadata object name and
the corresponding external field. Note that if you are developing an application locally, you will not
be able to browse external metadata. The type of field in the metadata -- for example text or integer --
is indicated by an icon.
5. Specify an existing data connection resource.
6. Check ″Key field″ if this field corresponds to a field in the external application that you want to
designate as the key field. Every data connection requires a key field -- the key field is the link
between the form and the back-end database or application. Note that key fields are always stored
locally as well as on the back-end.
7. (Optional) If you want data from fields other than the key field stored locally, mark each of these
fields as a Data field and select the ″Store locally″ option. For these fields, data will be stored in the
Domino database as well as in the back end database. Changes you make in the Domino database are
pushed back to the back end database. If the back end changes, you can manually refresh the Domino
database by pressing F9 with the document open or by closing and opening the document.

Importing data from an external database into an application


When you create a DCR and use it with fields that connect to an external database, you can create new
database records from within your Designer application. In order to display existing records from the
external database in your Designer application, you must import the records into your database. Before
you begin you must already have at least one DCR and at least one associated form with fields that
connect to an external database.
1. Follow the steps to create a database connection resource and associate it with a form containing
external fields.
2. Choose File - Database - Properties.
3. Click the Database Basics tab.
4. Make sure that ″Allow connections to external databases using DCRs″ is NOT checked.
5. Close and reopen the database.
6. Select Data Connections in the Shared Resources list in the Bookmarks pane.
7. Select the DCR that describes the records you want to import and click the ″Import external records″
button.
Designer displays a list of forms containing external fields.
8. Select the form that describes the records you want to import and click OK.
A DECS Administrator dialog box asks you to confirm your request to create documents based on
that form using the specified key field.
9. Click Yes to create the documents.
A dialog confirms the number of documents imported into the database. To view the documents,
open the database in the Notes client.

Chapter 12. Connecting to enterprise data 289


Note: Before you add or edit records, you must enable the ″Allow connections to external databases
using DCRs″ database property.

For more information on creating a DCR, see ″Creating a database connection resource″ and ″Using a
data connection resource on a form.″

Using ODBC to access relational databases


You can use the ODBC (Open Database Connectivity) Version 2.0 standard to access relational databases
such as DB2 or Oracle. Using formulas or scripts embedded in Domino objects, you can integrate the data
from many external databases into Domino applications. For example, a customer call-tracking
application accessed via the Notes client or Web browser can access customer financial data from an
ODBC-compliant relational database management system. ODBC is available on Windows, AIX, HP-UX,
OS/2, and the Mac PowerPC.

For more information on ODBC, see the Programming Guide.

Files required to use ODBC


When you install Designer, ODBC modules that support external data access install automatically.

In addition to these modules, you need an ODBC library (or shared object) and a driver for the type of
database you want to access. You purchase and install the library and driver separately. For Windows 95,
for example, you need these modules on your workstation:
v The ODBC 2.0 interface, available from Microsoft.
The interface defines the library of ODBC functions that perform the connection, query, and
data-retrieval processes.
v The Driver Manager, available from Microsoft and other vendors.
The manager loads the necessary drivers used to access the data and acts as an interface between
Domino and the drivers.
v The ODBC drivers, available from vendors or available for no charge to Notes and Domino users on
the Lotus Web site, http://www.lotus.com.
These handle communication between the Driver Manager and the databases. Domino supports a
variety of drivers. Each driver affects the specific capabilities of your application and comes with its
own installation, configuration, and Help documentation.

Note: Do not mix 32-bit and 16-bit versions of drivers, driver managers and Domino. When using
32-bit Notes clients or servers, use a 32-bit driver manager and 32-bit drivers. When using a 16-bit
Notes client or Domino server, use a 16-bit driver manager and 16-bit drivers to use ODBC to make
successful connections.
Some Lotus applications include ODBC drivers that are licensed specifically for use with that
application. Domino cannot use these drivers. If you try to use these drivers, a message appears stating
that you must have a license. You may be given a phone number or other information.

For more information about ODBC, see the Microsoft ODBC 2.0 Programmer’s Reference and SDK Guide
published by Microsoft Press.

Registering data sources for ODBC


Before your Designer application can access data in a relational database, you must register a data source
that tells the ODBC driver manager how to locate the data. Registering a data source ties a specific ODBC
driver with the data to be accessed. The registration information includes the data you want to access, its
associated server or directory, the back-end DBMS, and the network platform. To register this information
in a registration file (ODBC.INI in Windows 95), you use the Windows Control Panel, a utility such as the
Windows ODBC Administrator Utility, or a script or formula.
290 Application Development with Domino Designer 7
Note: For DataLens® programs that use Windows 3.1, ensure that the data sources named in those
programs are registered in ODBC.INI (not DATALENS.INI).

To register a data source for ODBC in Windows


You can use the operating system to register a data source for ODBC. Using the operating system allows
you to register the data source hardware, software, and database type.

Use the following steps to register a data source in Windows 2000. Other operating systems may require
slightly different steps.
1. From the Start menu, choose Settings - Control Panel - Administrative Tools - Data Sources (ODBC).
2. Click Add.
3. Select the driver you want, and click OK.
4. Enter the data source name, description, and requested information.
5. Some drivers require additional information; enter any other information necessary and click OK.
6. Click Close.

Setting up a view for ODBC access


You may use a view to display records from a data source that you access using ODBC. On the
Advanced tab of the Views properties box, you can enable the option ″For ODBC Access: Generate
unique keys in index.″ This option, in conjunction with a database command such as the NotesSQL
DISTINCT clause, suppresses the display of duplicate records so that only unique records display in the
view.

For example, suppose you request the following records from a relational database:

Record 1 Red Green Blue


Record 2 Yellow White Black
Record 3 Red Green Blue

If the property to generate unique keys in index is enabled, the following records will display in the
view:

Column 1 Column 2 Column 3


Red Green Blue
Yellow White Black

Record 3 does not display because it does not contain unique data.

For more information on using this option with the NotesSQL DISTINCT clause, see the product
documentation for Lotus NotesSQL on http://www.lotus.com/ldd/doc

Writing formulas and scripts to access relational databases


The following @functions access an external database through ODBC and return a value or list of values:
v @DbColumn returns all the values in one column of a table, or all the distinct values.
v @DbLookup returns selected values in one column of a table by matching keys.
v @DbCommand passes a command to an external DBMS and returns the result.

Chapter 12. Connecting to enterprise data 291


@DbColumn and @DbLookup can only retrieve data. They can’t add, delete, or modify data, or perform
other operations. @DbCommand can retrieve data or send other SQL statements that can change data.
LotusScript provides a wider range of capabilities including the ability to update the external database.

For more information about accessing external databases through ODBC and the ODBC versions of
@DbColumn, @DbLookup, and @DbCommand, see the Programming Guide.

The LotusScript Data Object (LS:DO)


This LSX-compliant module allows you to use LotusScript to write applications that incorporate data
from external non-Notes data sources. Your script may perform the following steps:
v Establish a connection with the data source.
Each connection requires the data source name. If the data source name is not already registered, you
must also provide additional information.
v Use SQL statements to send queries or other actions to the data source.
v Retrieve and use result sets.
v Read, modify, or add information into relational databases.
v Disconnect from the data source.
For more information on writing scripts to access external databases, see the Programming Guide.

292 Application Development with Domino Designer 7


Chapter 13. Including Java applets in applications
Applets are self-contained Java programs that can run in your Domino application. Java applets are often
used to add animation to Web applications. Although Java applets are mostly used for Web applications,
you can also include them in the following elements of a Domino application:
v Form -- The applet is included in each document created with that form.
v Document -- The applet is available only in the document.
v Page -- The applet is available only in the page.

A Java applet usually consists of a collection of files, with one file that contains the main class, or the
starting point for the applet. There can also be image files, archive files, and Java source files. You can
store Java applet files as follows:
v When you import an applet, the files are attached as hidden files to the form, document, or page
where you include the Java applet.
v When you link to an applet, files are stored on the Web and a URL reference to those files is stored in
the form, document, or page where you include the Java applet.
v When you set up shared applet resources, the files are stored in the database where you include the
Java applets that use those files.

Requirements and restrictions for Java applets


v Java applets are supported for most releases of Internet Explorer 4.x and 5.x and Netscape Navigator
4.x. Browser support is platform dependent. For the latest information on supported browsers, see the
topic ″Supported Web browsers″ in the Release Notes.
v Java applets created with Notes 4.6 and later will not work with previous releases of Notes, unless the
applet is stored on the Web and it has no parameters.
v Notes 6.0 and later support Java Virtual Machine (JVM) version 1.3.
v Any standalone Java applet that uses the Domino Objects (back-end classes) must run under the same
JVM version as was used to create the back-end class library (lsxbe). For example, if a standalone Java
applet is using lsxbe.so from Domino version 6, which uses JVM 1.3.1, then the standalone applet must
also be run using JVM 1.3.1. Any other configuration is not supported.

Overview of adding a Java applet to an application


To include a Java applet in an application:
1. Enable Java applets on your workstation.
2. Import the applet from files on your workstation or on a file server, or link to an applet on the Web.
3. Use the Programmer’s pane and the Properties box to set applet parameters, attributes, and
properties. Some applets will run with no modification, but most require that you set parameters or
attributes before you can run them.
4. Correct problems with the Java applets. If the applet doesn’t run, you may need to include additional
files or set additional parameters.
5. Optionally, you can set up shared applet resources, that is, set up related files so that they can be used
by several applets.

For more information about Java or to find applets you can use, see the Sun Microsystems Java Web site
at http://java.sun.com.

293
Enabling Java applets
Before you can add a Java applet to a Domino or Notes application, you must set up your workstation.
1. If you want to link to applets on the Web, make sure your Location document specifies a valid Web
proxy. See your system administrator if you have questions about setting up a Web proxy.
2. Choose File - Preferences - User Preferences.
3. In the Basics tab, scroll down the Advanced Options list and select ″Enable Java applets.″

Note: If ″Enable Java applets″ is not listed, check with your system administrator.
4. Click OK.

Importing an applet
Before you import a Java applet, you must enable Java applets on your workstation and make sure all the
related files are available on your workstation.
1. Open a page or form, or click in the rich text field of a document.
2. Choose Create - Java Applet.
3. In the Create Java Applet dialog box:
v Select ″Import an applet from the file system.″
v In ″Base Directory,″ enter the path for the applet files.
v In ″Class Name,″ enter the name of the main class.
To avoid typing the path and class name, click the folder icon to browse for the main class file for
the applet. Clicking the main class file inserts the class and the path in the correct fields.
4. Click Locate to see all related files for the applet.
5. Browse for the applet files from the local file system, or from the Shared Resources list, then do one of
the following:
v If you are using a shared resources applet, specify the database where the applet files reside. Select
the related applet files and click Add/Replace File.
v If you are inserting an applet that is packaged as a JAR file, select the JAR file, and click
Add/Replace File to include the JAR file.
6. Click OK twice.
7. (Optional) Set applet parameters, attributes, and properties.

Getting the main class name


One way to make sure you have the correct name for the main class (which you enter in the Create Java
Applet dialog box) is to use any text editor to open the associated *.HTML file and check for this HTML
tag:
<applet code=filename.class>

For example, the main class name for the following Java applet is ArcTest.class.
<applet code=ArcTest.class width=400 height=400></applet>

Selecting related files


Applet files can be of the following types:
v Class -- *.CLASS
v Archive -- *.JAR, *.ZIP, *.CAB
v Resource -- *.JPG, *.JPEG, *.GIF, *.AU
v Source -- *.JAVA

294 Application Development with Domino Designer 7


For most applets, you must select all class and resource files. Select the source files only if you plan to
send the applet to another user who wants to export them and change the applet.

If you are inserting an applet that is packaged as a JAR file, you can enter the path and the main class
name as described above. Note that browsing for the JAR file inserts the filename with a CLASS
extension in the Class Name field. In some cases, the file name and the main class name are the same; in
other cases, they are different and you must edit what appears in the Class Name field to be the correct
main class name.

If you have more than one applet in a form, document, or page, Notes stores only one copy of common
files.

Importing applets packaged as CAB or ZIP files


If you import an applet that is packaged as an archive file (such as either a CAB or ZIP file), consider the
browsers the application users have:
v For Internet Explorer users, include the CAB file.

Note: Domino does not display an embedded applet that is packaged as a CAB file.
v For Netscape users, include the ZIP and JAR files.
v If users are likely to use either or both browsers, include CAB, JAR, and ZIP files. Domino creates the
appropriate parts of the APPLET tag for these files. Netscape ignores the CABBASE (or CABINETS)
parameter and Internet Explorer ignores the ARCHIVE attribute.

Note: At the Folder tab of the Java Applet Properties box, you can view the applet files from an applet
you imported. If you did not import an applet, this field is blank.

Linking to an applet on the Web


Before you link to a Java applet on the Web, you must enable Java applets on your workstation.
1. Open a page or form, or click in the rich text field of a document.
2. Select Create - Java Applet.
3. In the Create Java Applet dialog box:
v Select ″Link to an applet on a Web server.″
v In Base URL, enter the URL where the applet files are stored. Do not specify the document that
references the applet. For example, use
http://java.sun.com:80/applets/Bubbles
instead of
http://java.sun.com:80/applets/Bubbles/index.html
v In the Base class name field, enter the name of the main class. Note that Java is case-sensitive to file
names.
4. Click OK.
5. (Optional) Set applet parameters, attributes, and properties.

Setting applet parameters


Some Java applets have parameters that use default values. You do not need to specify values for these
parameters. For applets that have parameters without default values, however, you must set parameter
values or the applet will not run. You can manually enter parameters and values, or you can paste all of
the parameters in the Programmer’s pane and edit associated values.

Chapter 13. Including Java applets in applications 295


To set individual applet parameters
1. Select the Java applet and, if the Programmer’s pane is not displayed, choose Java Applet - Java
Applet Parameters.
2. Click ″Applet Parameters″ in the Programmer’s pane.
3. Use any text editor and open the HTML file associated with the Java applet.
v If you imported the applet, check the HTML file on your file system.
v If you linked the applet, use a Web browser and check the HTML file on the Web. For example, on
Netscape you can choose View - Page Source to see the HTML file.
4. Click Add.
5. Enter the parameter name. For example, enter bgcolor for the following HTML tag:
<param name=bgcolor value="black">
6. Enter the corresponding value in the Parameter Value window. For example, enter black for the
example HTML tag in Step 5.

To set all applet parameters


1. Use any text editor or Web browser and open the HTML file associated with the Java applet.
2. In the HTML file, select all of the parameters and copy them to the Clipboard. For example, copy all
of the following text:
<param name=bgcolor value="black">
<param name=fgcolor1 value="red">
<param name=fgcolor2 value="magenta">
3. Select the Java applet and if the Programmer’s pane is not displayed, choose Java Applet - Java
Applet Parameters.
4. Click ″Applet Parameters.″
5. Click Paste to add the parameters and their values.

Tips
v To change a parameter value, click its name in the Programmer’s pane. Then change its value in the
Parameter value window.
v The parameter value is a formula; therefore, you must enclose text values in double quotes. In addition
to text strings, a parameter value can be an @function or a field name.
v If you are running an applet through a browser, you can add JavaScript to a form or document to
interact with the applet by calling its public methods or setting/getting its public properties.

Specifying applet parameters, attributes, and properties


After importing or linking an applet, you may need to set one or more of the following so that the applet
runs correctly:
v Parameters specify values the applet needs at startup and for correctly displaying the applet in your
application. The HTML file lists parameters for the applet in <param> tags.
To set parameters, use the Programmer’s pane and click ″Applet Parameters.″
v Body attributes specify values that are specific to a browser, such as alignment values. Attributes are
set at run time using a formula. Domino uses the formula to generate HTML code that is placed in the
<applet> tag.
To set attributes, use the Programmer’s pane and click ″HTML Body Attributes.″
v Alternate HTML attributes are usually used by browsers that do not support Java. Domino uses the
Alternate HTML attributes to generate HTML code that is placed in the <applet> tag.
To set Alternate HTML attributes, use the Programmer’s pane and click ″Alternate HTML.″

296 Application Development with Domino Designer 7


v Properties specify how an imported or linked applet appears in the page, form. You can also use Java
applet properties to hide the applet under specific conditions.
To set properties, use the Java Applet Properties box.

Setting HTML attributes


1. Select the Java applet and, if the Programmer’s pane is not displayed, choose Java Applet - Java
Applet Parameters.
2. Click ″HTML Body Attributes.″
3. Enter an HTML attribute in the formula window.

Setting Alternate HTML attributes


Use Alternate HTML for a browser that does not support Java.
1. Select the Java applet and if the Programmer’s pane is not displayed, choose Java Applet - Java
Applet Parameters.
2. Click ″Alternate HTML.″
3. Enter text or a formula.
For example, enter the following to tell users that their browser doesn’t work with the Java applet:
"You’re trying to run a Java applet with a browser that doesn’t support Java. You can run this
applet with Domino, Netscape Versions 3 and 4, or Internet Explorer Versions 3, 4, or 5."
4. (Optional) Use the ″Text to display when applet is not running″ property in the Java Applet Info tab
of the Java Applets Properties box to specify text that a browser displays when it supports Java but
cannot display the Java applet.

Setting properties
Use the Java Applet Properties box to set applet properties (such as height and width). You can also use
the Properties box to hide an applet by condition, or to hide an applet based on the browser accessing it.

To set applet properties


1. Select the Java applet and choose Java Applet - Java Applet Properties.
2. Click the Info tab to set any of these properties.

Property Description
Base class The name of the main class file.
DocBase Provided for information only. You cannot edit it.
CodeBase CodeBase is the path storing the class files, relative to the base class file. If
you linked to an applet on the Web, the URL of the directory containing
the applet is displayed, and you can edit the URL name. Otherwise, the
field is provided for information only.
Size The Height and Width fields set the size of the applet display area in the
Domino application where the applet is running. If the applet is too large
to run in the default size, you must reset these settings, using the height
and width settings from the HTML file. To determine the applet size, use
any text editor or Web browser to view the HTML file. Check the width
and height values specified in the <applet> tag. Enter these values in the
Width and Height fields. You can also specify a size for the applet as a
percentage of its parent window.
Text to display when applet is not Domino displays the text you specify when it can’t run the applet. Enter a
running simple text string, such as ″This applet is not working at this time.″
Applet uses Notes CORBA classes Enable the applet to access Notes objects.

Chapter 13. Including Java applets in applications 297


Property Description
Applet uses CORBA SSL security If you select ″Applet uses Notes CORBA classes,″ this setting becomes
available.

To hide an applet under certain conditions


You can hide an applet so it appears only under certain conditions in the form or page.
1. Select the Java applet and choose Java - Java Applet Properties.
2. Click the Hide-When tab and choose one of the following:
v Hide paragraph from
You can hide the applet according to what client is being used to access the application. For
example, you might hide an applet from a mobile user to improve the performance of the mobile
application. Or you might hide an applet from a Notes user but choose to display the applet to
Web clients.
v Hide paragraph when document is
You can hide the applet according to how the document is being used. For example, you might
hide the applet when the document is open for editing.
v Hide paragraph if formula is true
You can customize the conditions for hiding the applet by writing a hide-when formula that
specifies the criteria for hiding the applet.

To hide an applet based on the browser accessing it


1. Create a field named HTTP_USER_AGENT in the form where you imported or linked the applet, or
in the form used by the document where you imported or linked the applet.
2. For the field type, select Text and Computed for display. Optionally, you can hide the field.
3. Enter the following formula for the field value:
HTTP_USER_AGENT
When a user accesses a document that uses this form, the Web server fills in the field with a string
describing the browser type and version. The format of the string differs according to the browser.
Some examples:
Mozilla/3.0Gold (WinNT; I)
Mozilla/2.0 (compatible; MSIE 3.02; Update a; Windows 95)
4. Select the Java applet and choose Java Applet - Java Applet properties. Click the Hide When tab and
enter a formula that uses this field to hide the applet for a particular browser. Use the
@contains(HTTP_USER_AGENT; string) formula.
For example, use the following formula to hide the applet from Internet Explorer:
@Contains(HTTP_USER_AGENT; "MSIE")

Setting up shared applet resources


For large Java applets with multiple files, consider storing some of the related files as shared resources in
the database. When you set up files as shared resources, all the applets can use a single copy of the file,
instead of each applet storing its own copy. Then, if a file requires updating, you only need to update one
file. For applications that include multiple databases, one database can hold shared resources for use in
all the related databases.

To create a shared applet resource


1. Select the database where you want to set up the shared resources.
2. Choose Resources - Applets.

298 Application Development with Domino Designer 7


3. Click ″New Applet Resource.″
4. In the ″Base Directory″ field, enter the path where the Java applet files are stored.
5. Select the files you want to set up as shared resources from the ″Available Java Files″ list and click
Add/Replace file.
6. Click OK and enter a name. Click OK and Domino stores all the files as a shared resource with the
name you entered.
7. (Optional) Double-click the shared resource to open the Java Resource Properties box. At the Basics
tab, you can rename the shared applet and give it an alias. You can also view the files that make up
this applet.

To use a shared applet resource


You can include a shared applet resource from the current database, or from another database on your
desktop.
1. Open a document and click in a rich text field.
2. Choose Create - Java Applet.
3. In the Create Java Applet dialog box:
v Select ″Import an applet from the file system.″
v In ″Base Directory,″ enter the path for the applet files.
v In ″Class Name,″ enter the name of the main class.
4. Click Locate to see all related files and shared resources for the applet.
5. Select ″Shared Resources″ in the Browse list, specify the database where the shared resource resides,
and select the related applet files. Click Add/Replace File.
6. Click OK twice.

Stopping, selecting, and restarting applets


Applets start running automatically when you open a page, form, or document containing them.
However, to select and work with an applet, you must first stop it.

To stop an applet
To stop running one or all applets in a page, form, or document, choose View - Show - Java Applets
Running.

To select an applet
1. If the applet is running, you cannot select it. Choose View - Show - Java Applets Running to stop the
applet.
2. Click directly to the right of the applet.
3. Use the left arrow key to select the applet.

To restart an applet
When you open the page, form, or document containing an applet, it starts running automatically. To
restart an applet after you stopped it, double-click it.

Copying and deleting applets


You can copy applets and paste them in other applications or on another page, form or document within
the same application. You can also delete an applet you no longer need.

Chapter 13. Including Java applets in applications 299


To delete an applet and its related files
Before you delete an applet, remember that you cannot undo the deletion. Also, when you delete an
applet that you have imported, the related files are also deleted, unless another applet shares the files. If
you want to delete shared files, you must delete them in each page, form, or document that contains an
applet that uses them.
1. Stop the applet if it is running.
2. Select the applet and choose Edit - Delete.

To copy an applet
You can copy an applet from one page, form, or document to another page, form, or document. When
you copy an applet you have imported, all its related files are copied. When you copy an applet you
have linked to on the Web, only the link is copied.
1. Stop the applet if it is running.
2. Select the applet and choose Edit - Copy.
3. Click in the page, form, or document where you want to copy the applet.
4. Choose Edit - Paste.
5. (Optional) Set applet parameters, attributes, and properties.

Refreshing and exporting applet files


You can refresh an applet when you need to update existing files or add new files to the applet.
Exporting an applet allows you to copy all the applet files to your workstation or any other place to
which you have access.

To refresh applet files


1. Select the Java applet and choose Java Applet - Refresh.
2. Select files to add or replace, and click Add/Replace File.
3. Click Refresh.

To export files
1. Select the Java applet and choose Java Applet - Export.
2. Choose the directory to export the files to and click OK. Domino exports all the applet files and
creates subdirectories as needed.

Setting security for applets


To protect the security of the file system, Java security generally does not allow applets to access Notes
classes. However, you can set up the applet so that it can access Notes classes, thereby allowing it to
open a database and change data in it.

To set security for applets in Notes


To set up secure access for applets that will access the file system or Notes Java classes through Notes,
you must first set up an access control list (ACL), then set up an execution control list (ECL) for each
user or group. The ECL controls access to the file systems and to the Notes classes on the workstation.
1. In the database storing the Java applet, choose File - Database - Access Control and set up the ACLs.
2. Choose File - Security - User Security.
3. Enter password.
4. Select ″What Others Do.″
5. Select ″Using Applets.″

300 Application Development with Domino Designer 7


6. Under ″When applet is signed by,″ enter the users and/or groups that will have access to the file
system or Notes classes.
7. In the Allow list, select the options the users can use while running the Java applet.
8. Click OK.

When a user runs the applet, Domino checks for execution rights of the person or group that signed the
applet. If an applet is signed by a person or group without the correct authorization, Domino alerts the
user of the illegal operation. The user can stop the operation and not run the applet, trust the signer of
the applet one time, or automatically add the signer to the execution control list.

To set security for applets in Web applications


Complete these steps to set up secure access for applets that will access the file system or Notes Java
classes through a browser.
1. Use CORBA to write a Notes/IIOP applet that accesses the Notes classes.
2. Import the Notes/IIOP applet in a page, form, or document, using the same procedure as for any
other applet.
3. When you click Locate to Include the related applet files, make sure to include the NCSO.JAR file.
4. Import or link the Java applet that users will run.
5. Select the Java applet and choose Java Applet - Java Applet Properties.
6. In the Java Applet Info tab select ″Applet uses Notes CORBA classes.″

Assuming your browser and server are set up correctly, you should be able to use a supported browser
to view these embedded CORBA applets on a Domino server. You do not need to set alternate HTML for
the CORBA applet to run. When you check the setting that specifies the applet as a CORBA applet,
Domino automatically provides the HTML source code that the applet needs to make an IIOP connection
back to the server.

To extend the AppletBase class


An applet intended for run-time access of lotus.notes.noi extends AppletBase and puts its functional code
in the methods notesAppletInit() and notesAppletStart(), as shown in the sample code below, and in
notesAppletStop(). You do not have to distinguish between local and remote access. AppletBase will
make local calls if the applet is running through the Notes client and remote calls if it is running through
a browser.

Here is an example of an applet that makes NOI calls:


import lotus.notes.noi.*;

public class platform4 extends AppletBase


{
java.awt.TextArea ta;

public void notesAppletInit()


{
setLayout(null);
setSize(100,100);
ta = new java.awt.TextArea();
ta.setBounds(0,0,98,98);
add(ta);
ta.setEditable(false);
setVisible(true);
}

public void notesAppletStart()


{
try
{

Chapter 13. Including Java applets in applications 301


// Can also do getSession(user, pwd)
Session s = this.getSession();
if (s == null) { //we were not able to make the connection, warn user
ta.append("Unable to create a session with the server");
return;
}
String p = s.getPlatform();
ta.append("Platform = " + p);
}
catch(Exception e)
{
e.printStackTrace();
}
}
}

Saving applet data


Various actions in a Notes document, form, or page, such as resizing or editing applet parameters, cause
the applet to reinitialize to the state it was in when you opened the document, form, or page. When the
applet reinitializes, it loses data you entered and its current state. There are two methods for saving
applet data:
v Externalization
The applet stores specific information that it needs in order to return to the state it was in before it was
reinitialized. To maximize efficiency, it is recommended that you use externalization.
v Serialization
The applet stores all information, for example, each variable and its current value, each class, and all
header information.

Considerations
Although you can set up an applet for both externalization and serialization, Notes cannot support both.
An error is not reported, but one applet cannot do both.

In the Java applet itself, you must write methods to support the Java Externalize interface. If the applet
does not have these methods, you can still run the applet. However, the data cannot be saved, even if
you set up the parameters.

If you save data, keep these points in mind:


v If the applet is imported in a subform, the data from the subform has precedence over the data in the
form. Therefore, modifying an applet in a subform modifies all of the forms that include that subform.
v Data from an applet contained in a document takes precedence over the data stored in a form or
subform.

If you imported the applet in a document and you are saving data, the data file will be copied if you
export the applet. If you imported the applet in a form, the data file will not be copied if you export the
applet from a document you created with the form.

Externalization
There are three parameters available to direct Notes to save and reuse externalized data:
v ReadExternalData
Directly after reinitialization, the applet uses this parameter to load data previously saved.
v ExternalData
Any time after reinitialization, the applet uses this parameter to load data previously saved.
v WriteExternalData

302 Application Development with Domino Designer 7


After a Notes save event, the applet uses this parameter to save current data. The data is saved as an
external object with an attachment in the document that references it. The attachment is hidden and
cannot be seen by the user.

Usually you do not need to use both ReadExternalData and ExternalData. Use either one depending on
when you want the applet to load data.

Generally, the values you assign to the parameters are the same.

To set up externalization
1. Select the Java applet and choose Java Applet - Java Applet Parameters.
2. Click ″Applet Parameter″ in the Programmer’s pane.
3. If you want the applet to load data as soon as it has completed initialization, click Add and do the
following:
v In the Parameter Name field, enter ReadExternalData and click OK.
v In the Parameter value window, enter the value for ReadExternalData. Its value is the name of a file
that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
4. If you want the applet to load data at some other point after initialization, click Add and do the
following:
v In the Parameter Name field, enter ExternalData and click OK.
v In the Parameter value window, enter the value for ExternalData. Its value is the name of a file that
is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
Notes appends the value with the entire URL of the data file.
5. If you want the applet to save data at the end of the session, click Add and do the following:
v In the Parameter Name field, enter SaveExternalData and click OK.
v In the Parameter value window, enter the value for SaveExternalData. Its value is the name of a file
that is attached to the page, form, or document where the applet is stored. For example, enter:
mydata
If the file attachment does not exist, Notes creates it and stores the data in it.

Example HTML code


<PARAM NAME="readexternaldata" VALUE="mydata">
<PARAM NAME="writeexternaldata" VALUE="mydata">

Serialization
There are two parameters available to direct Notes to save and reuse serialized data:
v Object
The applet uses this parameter, a standard HTML parameter, to load (using Java VM and VM)
previously saved applet data in the serialized object. The object must exist before the applet attempts
to load it, or the operation fails.
v WriteObject
After a Notes save event, the applet uses this parameter, a Notes extension, to save the data. The data
is saved as a serialized object in a hidden attachment to the document. The user cannot see the
attachment.

Chapter 13. Including Java applets in applications 303


To set serialization
1. Select the Java applet and choose Java Applet - Java Applet Parameters.
2. Click Applet Parameters in the Programmer’s pane, and then click Add.
3. To load the previously saved data, enter the following in the Parameter Name field and click OK:
Object
4. In the Parameter value window, enter the value for Object. Its value is the name of a file that contains
the previously saved state information from the WriteObject parameter. This file is attached to the
page, form, or document where the applet is stored. For example, enter:
mydata
5. To save the applet data, click Add, enter the following in the Parameter Name field, and click OK:
WriteObject
6. In the Parameter value window, enter the value for WriteObject. Its value is the name of the file that
is attached to the page, form, or document where the applet is stored. For example, enter:
mydata

Example of HTML code


Your parameters might look like this:
<PARAM NAME="object" VALUE="mydata">
<PARAM NAME="writeobject" VALUE="mydata">

Tips and troubleshooting for Java applets


When the applet runs, the status bar displays messages such as ″Loaded <applet-name>,″ ″Initialized
<applet-name>,″ and ″Started <applet-name>.″ If the applet does not load properly, a dotted gray
rectangle appears instead. Review the sections below and choose File - Tools - Show Java Debug Console
to examine the applet and determine the problem.

Troubleshooting an applet that is not running


v If the applet is linked to a Web site, check that your Web proxy is running. Get the name of your Web
proxy from your Location document. If you are running Windows, go to the DOS prompt and use the
ping command followed by the proxy name to determine if your connection is valid. If the ping
command returns an error rather than a reply, contact your system administrator for help restoring
your Web proxy.
v Check that you included all the necessary applet files. Choose Java Applet - Refresh to add additional
files to the applet. To make sure you have all the files, select All for File Types and click Select All to
include everything.
v Check that you entered the correct name for the applet files. Java is case sensitive, so the file names
must match exactly.
v Make sure you correctly specify the parameters required by the applet. Choose File - Tools - Show
Debug Java Console and view the messages reported by the Java applet. Check for missing parameters
and add in parameters that are required.
v Make sure that applets which use the Domino Objects (back-end classes) are running under the same
JVM version as was used to create the back-end class library (lsxbe). For example, if a standalone Java
applet is using lsxbe.so from Domino version 6, which uses JVM 1.3.1, then the standalone applet must
also be run using JVM 1.3.1. Any other configuration is not supported.

Accessing resource files


Java applets frequently use resource files such as images and audio files. There are three common ways
that applets access these files:
v By specifying a full URL for the file, for example, http://www.someplace.com/image.gif.

304 Application Development with Domino Designer 7


v By using the applet class getDocumentBase method to construct a URL relative to the location of the
document in which the applet is found.
v By using the applet class getCodeBase method to construct a URL relative to the code base of the
applet, that is, the location from which the applet’s files were loaded.

Depending on what method you use, Domino may not be able to locate resource files for the applet. The
getCodeBase method is the most reliable method for specifying resource files. If you experience problems
with applets not finding resource files, modify your applet to use getCodeBase. Recompile the files and
choose Java Applet - Refresh to replace these files in the document.

Specifying a full URL


If your applet specifies a full URL to locate a resource file, for example,
getImage(″http://www.someplace.com/images″, ″image.gif″), the applet attempts to find the file at that
URL. This usually works when running applets within the Notes client in a document served by a
Domino server, as long as you correctly configure your Notes client to access files on the Internet.

Similarly, you can access images attached to Notes documents by constructing the Domino URL to
include a ″$FILE″ -- for example,
getImage(″http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE″, ″image.gif″). As
above, the Notes client must be able to access the Domino server in order for an applet running in the
Notes client to be able to access this file.

One of the drawbacks of specifying a full URL for an applet resource file is that it may be slow to access
this file through the Internet and not all Notes clients are set up to directly access the Internet. Also, this
course of action assumes that the location of this file will not change. If these are not concerns, spcifying
a full URL is a reliable way to access resource files.

Using getDocumentBase
The least reliable means of specifying resource files is the getDocumentBase method. The
getDocumentBase method of specifying resource files returns the base URL (that is, the full document
URL minus the document file name) of the document in which the applet is located. For example, if an
applet is running in a document at:
http://www.someplace.com/test/example.html

the getDocumentBase method returns a URL specifying:


http://www.someplace.com/test

Some applets use this method to specify a URL for resource files -- for example,
getImage(getDocumentBase(), ″image.gif″). Using the above URL as an example, the applet would be
looking for the image file at the URL
http://www.someplace.com/test/image.gif

Note, however, that the Domino URL for a document does not simply refer to a file; instead, it is a
command for the Domino server to generate the HTML representing a document. If you use the
getDocumentBase method as a Domino URL, you get unexpected results. For example, suppose you
linked an applet with the following Domino URL:
http://www.someplace.com/database.nsf/MasterView/862..12E?OpenDocument

In this case, using the getDocumentBase method in conjunction with the getImage call returns:
http://www.someplace.com/database.nsf/MasterView/image.gif

The applet cannot find the file because the document ID is gone and the image is an attachment to a
document, requiring a $File qualifier as part of its name.

Chapter 13. Including Java applets in applications 305


Because the document’s ID has been removed (and since the image is in an attachment in the document
and thus needs ″$FILE″ to qualify the file name), the requested image cannot be found by the applet.

Using getCodeBase
The most reliable means of specifying a resource file for an applet is the getCodeBase method. The
getCodeBase method returns the base URL from which the applet was loaded. The codebase for an applet
can be specified by the CODEBASE attribute in the APPLET tag. When Domino generates the HTML for
an applet which has been inserted into a Notes document, it generates a full URL for the CODEBASE
attribute. For example, given the example above, the getCodeBase method returns:
http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE

When used in conjunction with resource calls, such as getImage calls, getCodeBase correctly specifies the
resource file. For example:
getImage(getCodeBase(), "image.gif")

yields the following URL when the applet is served by Domino:


http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE/image.gif

This results in a URL that allows the applet to successfully find the file.

Modifying parameter values to locate resource files


Some applets include parameters that refer to resource files or to directories containing resource files. For
example, an applet may include a parameter specifying a file for use as a background image or a
directory for audio files. You may need to edit the applet so that these parameters are relative to the code
base, rather than to the document base.

If you are not building the applet yourself, for example, if you are linking to an applet on the Internet, or
if you obtained a set of CLASS files without the source code, you might need to edit a parameter value
after inserting the applet into a form or document. In that case, prepend the string ″$notes_codebase″ to
the parameter value.

For example, instead of using ″images/image.gif,″ use ″$notes_codebase/images/image.gif″ as the


parameter value. Domino converts any occurrences of the $notes_codebase string in a parameter into the
code base for the applet. The parameter value ″$notes_codebase/images/image.gif″ is therefore converted
by Domino to:
http://www.someplace.com/database.nsf/MasterView/862..12E/$FILE/images/image.gif

Since this effectively means that you are providing a full URL when specifying the parameter value, the
getDocumentBase method in the applet is overridden, and the applet will be able to find the resource file.

306 Application Development with Domino Designer 7


Chapter 14. Including Java servlets in Web applications
A servlet is a Java program that is run by the Domino Web server in response to a browser request.
Servlets provide a convenient way to add powerful functionality to your Web application. In some ways,
servlets act like CGI programs, but they are more tightly integrated with the server and can take
advantage of special Java classes. For example, a servlet may connect to a relational database or
enterprise system and get data in response to a Web browser request.

Domino supports both Java servlets and Java applets for Web applications. The most important difference
between these types of Java programs is how they are run. Servlets are ″server-side″ programs; a servlet’s
Java class is loaded and run entirely within the Domino server and the result from the servlet, usually a
page of HTML, is returned to the browser. In contrast, applets are ″client-side″ programs; an applet’s Java
class is downloaded to the browser and is run by the browser. Therefore, applets require Java support in
the browser, but servlets do not.

Servlets for Domino must conform to the Java Servlet API Specification, an open standard published by
Sun Microsystems, Inc.

Running a servlet in Domino involves writing the servlet, enabling servlet support in Domino, and, if
necessary, setting servlet properties.

Comparing agents, servlets, and CGI programs


Agents, servlets, and CGI programs all allow you to extend the functionality of your Domino Web
application. Agents can be tightly integrated with a Web application through the form WebQueryOpen
and WebQuerySave events. Servlets have special features available through the Servlet API classes, such
as session and cookie management. Due to the growing popularity of Java, the trend today is to use
servlets rather than CGI programs for new development. However, there is a large selection of
off-the-shelf CGI programs already available.

If you are writing your own application and need to program some functionality on the server, you may
have a choice of which type of program to use. Each type of program has its advantages and will be the
best choice in particular situations. Here are some suggested uses for each type of program:

Program type Best uses


Agent Programs that perform Domino actions when documents are read or posted.

Programs that need to be run on a schedule or when database actions occur, such
as the arrival of new mail.
Servlet Programs that use standard Java interfaces such as JDBC.

Programs that use HTTP session maintenance or cookies.

Complex or resource-intensive Java programs.


CGI program Programs that need low-level access to system resources.

Programs that interface with another product through a non-Java API.

Here are some useful comparisons of the properties of these programs.

307
What language can the program be written in?
v Agent: Java, LotusScript, or Notes formula language. All are inherently cross-platform.
v Servlet: Java. Inherently cross-platform.
v CGI program: Platform scripting languages; that is, any language compiled into an executable file, or
cross-platform languages such as Java or Perl.

Where is the program stored?


v Agent: Stored in a Domino database, which means that agents take advantage of database replication
and server clustering.
v Servlet: Stored in the file system, usually in the domino\servlet directory.
v CGI program: Stored in the file system, usually in the domino\cgi-bin directory.

How is the program invoked by a Web user?


v Agent: Invoked automatically by a WebQueryOpen or WebQuerySave event, or invoked directly by an
OpenAgent URL (for example, http://acme.com/sales.nsf/results?OpenAgent). Agents can also be
triggered by server events, such as the arrival of new mail, or on a scheduled basis.
v Servlet: Invoked directly by a URL. Domino recognizes two types of servlet URLs. The first type
specifies the servlet by its name (for example,
http://acme.com/servlet/SQLDatabaseQuery?month=june). The second type specifies a file extension
that the Domino administrator has mapped to a servlet (for example,
http://acme.com/sqlquery.esp?month=june).
v CGI program: Invoked directly by a URL (for example, http://acme.com/cgi-
bin/filesearch?string=widget).

When is the program loaded and unloaded by the server?


v Agent: Loaded every time it is invoked and unloaded when it has finished.
v Servlet: Loaded once; stays loaded until the HTTP server task is shut down or restarted. This gives
servlets a significant performance advantage over agents or CGI programs. However, this also means
that the servlet classes can be accessed from many requests simultaneously, so you must make sure
that the servlet code is thread-safe.
v CGI program: Loaded every time it is invoked and unloaded when it has finished.

How can the program interact with Domino?


v Agent: LotusScript and Java agents can use the Domino object classes. Formula agents can use most
@functions.
v Servlet: Can access Domino through the Common Object Request Broker Architecture (CORBA)
interface.
v CGI program: Can access Domino through the CORBA interface, or through the Domino C or C++ APIs.

What security is available for the program?


v Agent: To invoke an agent, a Web user must have at least Depositor access to the database containing
the agent. An agent can run with the identity of its creator or the user. The full range of Domino
security features applies to operations performed by the agent.
v Servlet: Access to the servlet can be controlled by file-protection documents in the Domino Directory. If
the servlet accesses Domino through the CORBA interface, it can specify a Domino user name and
Internet password. Domino security applies to all CORBA operations.

308 Application Development with Domino Designer 7


v CGI program: Access to the program can be controlled by file-protection documents in the Domino
Directory. If the program accesses Domino through a C API, it takes the identity of the server ID; if it
uses the CORBA interface, it can specify a user name and Internet password. In both cases, Domino
security applies.

Running servlets in Domino

Writing the servlet


To write a servlet, you need a Java compiler and the servlet API. You can obtain both from Sun
Microsystem’s Web site at http://java.sun.com. Download the Java Development Kit (JDK), which
includes the compiler and other basic tools, and the Java Servlet Development Kit (JSDK), which includes
the servlet API specification, the servlet .JAR file (jsdk.jar), and example servlets. The Sun site also
provides links to other servlet resources on the Web.

You can also write servlets using any popular Java development environment. As a convenience, a copy
of jsdk.jar is included in the Domino server and Designer installation kits. It is identical to the file
supplied in Sun’s JSDK.

Sun periodically updates the JDK and JSDK. Lotus Domino Designer Release 6 supports JDK 1.3 and
JSDK 2.0. Domino quarterly maintenance releases (QMRs) often incorporate Sun’s upgrades, so you
should check the QMR Release Notes to verify the supported JDK and JSDK versions.

Enabling servlet support in Domino


Servlets are loaded and called by the Domino Java Servlet Manager, a part of the HTTP server task. The
runtime Java support for servlets is provided by the Domino Java Virtual Machine (JVM). When the
HTTP task is started, it can automatically start the servlet manager and load the JVM. The HTTP task will
write status messages for these operations to the server console and log file.

The servlet manager is controlled by settings in the Domino Directory Server document. The settings are
located on the Internet Protocols - Domino Web Engine tab of the Server document. The settings are as
follows:

Setting Options
Java servlet support None: (default) The HTTP task does not load the servlet manager or the JVM.

Domino Servlet Manager: The HTTP task loads both the JVM and the servlet
manager.

Third Party Servlet Support: The HTTP task loads the JVM, but not the Domino
servlet manager. This allows the use of third-party servlet managers such as the
IBM WebSphere Application Server.
Servlet URL path The path in a URL that signals Domino that the URL refers to a servlet. The default
is /servlet.

Chapter 14. Including Java servlets in Web applications 309


Setting Options
Class path A list of one or more paths which the Servlet Manager class loader will search to
find servlets and their dependent classes. This setting allows you to add additional
paths. You may specify directories, JAR files, and ZIP files. Paths may be absolute
or relative to the Domino data directory. The default is domino\servlet.

Examples:

Relative directory path: domino\servlet

Absolute directory path: c:\apps\MyServlets

JAR file: c:\javamail\mail.jar

ZIP file: domino\servlet\sql.zip


Servlet file extensions A list of URL file extensions that signal Domino that a URL refers to a servlet. Each
extension in the list must be mapped to a single servlet by a directive in the
servlets.properties file. The default is no extensions.

The following settings control the Domino Servlet Manager’s runtime support of the Java Servlet API
HttpSession interface. A servlet that does not use this interface is not affected by these settings.

Note: The HttpSession interface support is completely separate from the HTTP session authentication
feature in Domino.

Setting Options
Session state tracking Enabled: (default) The servlet manager periodically checks the user activity of all
HttpSession instances. Sessions that have been idle for a given period of time are
automatically terminated. The servlet manager calls the instance’s
HttpSession.invalidate() method to inform the servlet that the session is being
terminated.

Disabled: Sessions will not be checked for inactivity.


Idle session timeout The number of minutes of user inactivity to wait before terminating a session. The
default is 30 minutes.
Maximum active sessions The number of simultaneous active sessions allowed. The default is 1,000 sessions.
When this limit is reached, the sessions that have been idle the longest are
terminated.
Session persistence Enabled: When the HTTP task exits, the servlet manager saves session data to a
disk file called sessdata.ser in the Domino data directory. The session data will be
reloaded when the HTTP task is restarted. Objects that the servlet has bound to
sessions will also be saved if the objects implement the java.io.Serializable interface.

Disabled: (default) All session data is discarded when the HTTP task exits.

Loading servlet classes with the JVM loader


The Servlet Manager class loader will not load classes that use native code, create custom class loaders,
or perform certain other restricted operations. If your servlet requires a class that can’t be loaded by the
Servlet Manager, you can try loading it with the Domino JVM class loader. The JVM loader is normally
responsible for loading classes from the standard Java archives installed with Domino, in particular the
java.* and lotus.* packages. You can force a servlet to be loaded by the JVM loader rather than by the
Servlet Manager loader by moving the servlet from the Servlet Manager classpath to the JVM classpath.
The JVM classpath is specified by the NOTES.INI variable JavaUserClasses.

310 Application Development with Domino Designer 7


Tip: You can also load classes in the NOTES.INI file when a class your servlet requires conflicts with
classes in the Domino-supplied LotusXSL.jar file. If you load and run a servlet and get a ″Verify Error″
message, try moving the JAR files for the servlet from the Servlet Manager classpath to the
JavaUserClasses statement in the NOTES.INI file.

Setting properties for servlets


Special properties for individual servlets can be specified in a text file called servlets.properties located in
the Domino data directory. The following properties can be specified:
v Alias
v Initialization arguments
v URL extension mapping
v Load at Servlet Manager startup

These properties are specified by directives in the servlets.properties file. The general syntax of a directive
is:
servlet(s).<name>.<property>=<value(s)>

Directives are case-sensitive. The servlets.properties file can also contain blank lines and comment lines
starting with the ″#″ character. The servlets.properties file is optional. The default properties for servlets
are: no alias, no initialization arguments, no extension mapping, and load servlets on demand.

Servlet aliases
The alias directive has this syntax:
servlet.<alias-name>.code=<class-name>

For example:
servlet.SQLQuery.code=sql.database.query.Servlet

As a security measure, Domino does not allow servlet names containing periods to be used in a servlet
URL. This prevents malicious users from trying to load arbitrary Java package classes through the Servlet
Manager. If your servlet has a package name, you must assign an alias to it. The above example allows
the servlet sql.database.query.Servlet to be invoked by a URL such as
http://acme.com/servlet/SQLQuery?month=june. Aliases are also useful for hiding the actual names of
servlets from users.

You can assign more than one alias to a servlet. The servlet manager will create a new instance of the
servlet on receiving the first URL that refers to each alias. The servlet manager will call the servlet’s init()
method when a new instance is created. Since the alias name can be used in other directives in the
properties file, the instances can be given different properties. For example, you could specify a separate
initialization argument directive for each alias. Also, because the servlet classes are only loaded once even
if multiple instances are created, the instances of the servlet can share data by using static class variables.

As a security feature, if you give a servlet an alias, the servlet cannot be directly referenced in a URL by
its class name. This allows you to hide the actual name of a servlet.

Initialization arguments
You can specify initial data for a servlet in the properties file. The servlet can access the data by using the
method ServletConfig.getInitParameter. The initialization directive has this syntax:
servlet.<alias or class name>.initArgs=<name1=value1>,<name2=value2>,...

Multiple arguments can be specified, separated by commas. For example:


servlet.SQLQuery.initArgs=target=db2,user=Domino,cacheSize=30

Chapter 14. Including Java servlets in Web applications 311


URL extension mapping
The URL extension mapping directive has this syntax:
servlet.<alias or class name>.extension=<extension> <extension> ...

You can assign more than one extension to a servlet, separating each from the next by a space. All
extensions must also be included in the ″Servlet file extensions″ setting in the Server record. For example,
to cause Domino to call the SQLQuery servlet whenever a URL specifies the extension ″sql″ or ″sq,″ add
″sql,sq″ to the server setting and add this directive to the properties file:
servlet.SQLQuery.extension=sql sq

This allows a user to invoke the servlet with a URL like this:
http://acme.com/query.sql?month=june

Load on startup
By default, the servlet manager loads a servlet’s class files into memory the first time a URL is received
that refers to the servlet. However, you can specify that one or more servlets should be loaded
immediately when the servlet manager is started. This prevents users from experiencing delays when
servlets are first requested from URLs.

The startup directive has this syntax:


servlets.startup=<alias or class> <alias or class> ...

Note that ″servlets″ is plural and that the servlet names must be separated by spaces.

If you have given a servlet one or more aliases, you can include the aliases in the startup directive. This
will cause the servlet manager to load the servlet classes and then create an instance for each alias.

After the servlet manager loads a servlet’s classes, they stay in memory until the Domino HTTP task is
stopped by the console command ″tell http quit″ or restarted by the console command ″tell http restart.″
Before unloading a servlet, the servlet manager calls the destroy() method for each instance of the servlet,
to give it a chance to clean up resources.

A class that has been loaded by the JVM class loader remains loaded until the HTTP task is stopped. The
″tell http restart″ command will not unload the class.

Example properties file


Here is an example of a servlets.properties file:
# Properties for the sql servlet
servlet.SQLQuery.code=sql.database.query.Servlet
servlet.SQLQuery.initArgs=cache=30
servlet.SQLQuery.extension=sql
# Properties for the mail servlet
servlet.MailServlet.initArgs=mime=enabled,smime=disabled

# Both servlets should be loaded at startup


servlets.startup=SQLQuery MailServlet
# end of file

312 Application Development with Domino Designer 7


Chapter 15. Including XML in Designer applications
Extensible Markup Language (XML) is a standard for creating markup languages that describe the
structure and meaning of data in a document. XML separates the content of a document from its
presentation and provides a common format for transferring data across the World Wide Web (WWW) or
company intranet. The result is a technology that makes data available regardless of the proprietary
systems involved.

How XML works

XML isn’t a markup language itself, but a set of rules that enables you to create tags as you need them.
In XML, a document is broken into parts and each part is separate. The way a document looks is
determined by a style sheet, the content of a document is contained in a separate file, and the definitions
of the tags are stored in another file called a Document Type Definition (DTD). Using a common data
format and separating data from its formatting and its tag definitions makes the data readily accessible
and reusable. Data from one application can be used in another application by changing the DTD or style
sheet. The style sheets currently being used for XML are Cascading Style Sheets (CSS) and Extensible
Stylesheet Language Transformation (XSLT). CSS styles data directly on the client, while XSLT is used to
transform XML data into HTML, or another form of XML.

XML also breaks the contents of a document down into its basic structural elements. For example, an
online book catalog contains information about each book including the title, author, publisher’s list price,
retail price, sale price and ISBN number. With XML you can create a tag for the book itself, but you can
also create tags that describe each of its sub elements so that it’s possible to differentiate between data
such as the publisher’s list price, retail price and sale price. The ability to make this kind of distinction
between elements in a document makes it possible for computers to process information more accurately
with less human intervention.

Server-to-server applications where information is transferred from one system to another is just one way
in which XML is making information processing more powerful. Using XML, applications can be
developed that are fully automated. For example, a company has an application that employees use to
update their own benefits information. Using a browser or the Notes client, employees update their
benefit selections at designated times during the year. When they have completed their changes, a server
such as Domino passes the employee’s information in XML format to another server for processing. The
second server runs a Java servlet to complete the transaction by interacting with a backend human
resources application such as PeopleSoft. When the update is complete, the server notifies Domino that
the employee’s benefits reflect the new selections.

The advantages of XML

The excitement surrounding XML relates to the advantages of such a robust and flexible tool. Some of the
advantages of XML are that it is:
v Easy to use because it resembles HTML
v Extensible, that is, you can define tags that describe your data
v Nonproprietary
v Perfect for large, complex documents

XML technology represents a capacity for sharing information that didn’t exist before. Virtually any kind
of data can be rendered in XML, encapsulated, moved across a network and processed automatically
between servers. Domino provides a secure environment for developing the applications that make this
kind of information sharing possible.

313
For information about creating XML applications, visit the Lotus Web site at http://www.lotus.com/xml.

What is DXL?
DXL is Domino XML-- that is, Domino data expressed as XML according to the tag definitions in the
Domino Document Type Definition (Domino DTD). DXL allows you to see all or part of a Domino
application as XML, much as you might view the source HTML for a Web page. This lets you apply the
advantages of the flexible XML environment to a Domino application.

For example, you can use the DXL Viewer utility to display one or more design elements as DXL or use
the DXL Exporter utility to write that same information to a file. Once exported in this way it would be
possible to integrate all or part of your application design into other XML-aware applications. But what if
the other application has a different definition for elements like forms and views? That’s where the DXL
Transformer becomes useful. This utility can convert the DXL representation of Domino design elements
into other XML formats using definitions in a stylesheet (XSL). Well-formed HTML qualifies as another
XML format so the DXL transformer can function as a type of report writer by importing design elements
as DXL documents, applying an XSL stylesheet to the design elements and reformatting the output as
HTML. For instance, one of the sample stylesheets that ships with Designer (’REPORT-AllLSinForm.xsl’)
searches for all the LotusScript code contained in a form and presents it in an easy to read outline. For
example, if you select the Memo form from the Lotus Notes mail template and apply the stylesheet
″REPORT-AllLSinForms.xsl″ your output will appear as follows:

Thus, if you need a particular design analysis not available via the standard Design Synopsis feature, you
can design your own report by creating a new XSL stylesheet. The DXL utilities give you full control over
both the content and format of the output document.

For more information on the Domino DTD, see the Programmer’s Guide.

314 Application Development with Domino Designer 7


Domino applications and XML
One of the clearest benefits of XML is that because this emerging technology builds on the standards of
HTML and SGML, it represents an evolution of data sharing rather than a revolution that requires new
hardware and software. XML marries perfectly with Domino applications. Where XML gives the power to
describe data and share it across a network, Domino provides all of the other tools you need to make that
data sharing secure, reliable, and efficient. In addition to providing a medium for writing and serving
XML data to an XML parser, Domino Designer also provides:
v A powerful development environment including a set of programming tools for building your
collaborative e-business applications.
v Layers of security you need to protect data -- from database access control down to individual field
encryption.
v Search capabilities for users to efficiently locate data.
v Messaging for workflow operations such as order confirmation, e-mail notification, and document
review.

In addition to the development tools provided with Domino Designer, you get the connectivity services
that allow you to connect your application with major backend systems, including:
v ERP systems, such as SAP, PeopleSoft, Oracle, and JD Edwards
v Relational databases, such as DB2, Sybase, and Oracle
v Transactional systems, such as IBM CICS, MQ Series, WebSphere, and BEA Tuxedo

Applications enhanced with XML


To illustrate how to integrate XML in a Designer application, consider an online site that sells books,
among other things. The XML tags that describe data about each book are standardized tags such as
<bookTitle> and <bookAuthor>. Any application that processes data about books can use these standard
tags to describe specific data about books. The application can interact with book vendors as well as with
purchasers using this standard data format.

Just about any application can work with XML. For example, consider an auto supply store that
maintains an e-commerce site with an online catalog of auto parts. With XML as the common language to
describe part information, the purchasing agent can pull information from various vendors about part
pricing and availability directly into a Domino database. Users can access this database for up-to-date
information about parts they can order online. Domino then provides all of the necessary tools to
complete secure online transactions for ordering parts and managing inventory.

Another example is a human resources ″self-service″ application that employees can use to access and
manage their own personal data. For example, the company can publish benefits information on an
intranet site and allow employees to make their benefit selections online using a Notes client or a Web
browser. After making selections, an employee submits the data in XML format to a server such as IBM’s
WebSphere Application Server. The server uses a Java servlet to pass the data along to the HR backend
system -- for example, a PeopleSoft database -- and notifies Domino when the transaction is complete.
The XML tags describe the data being passed so that the data means the same in the Domino application
as it does in the PeopleSoft database.

Ways to include XML in a Designer application


There are several ways you can include XML in a Designer application and serve the data to an XML
parser.

You can enter XML tags that describe data on a form or a page. By treating the contents of the form or
page as XML, you can serve the XML to an XML parser that can interpret the tags. XML describes the
data being presented. To format and style the data on the form or page, you can use a stylesheet, created

Chapter 15. Including XML in Designer applications 315


with the Extensible Stylesheet Language (XSL) to transform the data into HTML, or you can use a
Cascading Style Sheet (CSS) to style the XML directly on the client.

You can also generate XML data with a view by including XML tags in column formulas. To pass the
view to the server, you must embed it on a page or view in order to wrap the whole view in the correct
XML document definition tags.

You can use agents or servlets to dynamically generate or store XML. Agents are useful for running a
scheduled process in a Domino application. Servlets run on the server based on a request from a Web
browser.

For information about the Domino DTD and how to generate XML using Java methods, see the
Programming Guide.

XML terminology
The following is a list of important XML-related terms and definitions.

attribute: A name and its value which are included inside an XML tag. For example, in the tag <book
isbn=″0-395-73679-X″>, isbn is the name and its value is 0-395-73679-X (values are enclosed in single or
double quotes).

Cascading Style Sheet (CSS): A style sheet that defines the appearance of an XML or HTML document
directly on the client.

child: An XML element located inside another XML element.

content model: In XML, the expression specifying what elements and data are allowed within an
element.

Document Type Declaration: A declaration that contains, or points to, a Document Type Definition
(DTD).

Document Type Definition (DTD): A collection of markup declarations contained in a single, or multiple
XML files, that describes an XML document’s permissible elements and structure. A DTD ensures that a
uniform structure will be used across all documents.

DTDless: Refers to an XML file with no DTD. A browser processes the XML document structure while
it’s reading the document because it has no DTD to define the structure in advance.

DXL: Domino Extension Language. DXL is the representation of Domino design elements as XML using
the Domino DTD.

element: A block of text in an XML document made up of a start and end tag, and the content between
the tags. Empty tags are also elements. For example, <price>$12.60</price> and <price/> are both
elements.

encoding attribute: An attribute inside the XML declaration that indicates the level of encoding in the
document. For example, <?xml version=″1.0″ encoding=″UTF-8″> indicates that a compressed form of
unicode will be used that assigns one byte for ascii characters, two bytes for other common characters,
and three bytes for all other characters.

Hypertext Markup Language (HTML): A markup language consisting of predefined tags used to
describe a document’s structure and appearance.

316 Application Development with Domino Designer 7


parent: An XML element which contains another XML element. The XML element contained by the
parent is the child element.

root element: The element that contains all of the other elements in an XML document.

schema: A technology-neutral term for the definition of the structure of an XML document.

SGML: Standard General Markup Language. A markup language which serves as the basis for XML.

standalone attribute: An optional attribute inside an XML declaration that indicates whether the
complete XML document is contained in the current file, or if it needs to import other files. For example,
<?xml version=″1.0″ standalone=″yes″?>.

style: Defines the characteristics of an element’s appearance such as font, boldface, italics.

stylesheet: A document specifying the style information for another document.

valid XML: XML that meets the constraints defined by its Document Type Declaration.

version attribute: An attribute inside the XML declaration that indicates the version number of the XML
specification a document conforms to. For example, <?xml version=″1.0″?>.

well-formed XML: An XML document is well-formed if there is one root element, and all its child
elements are nested within each other. Start tags must have end tags, and each empty tag must be
designated as such with a trailing slash (<emptyTag/>). Also all attributes must be quoted, and all
entities must be declared.

XML: Extensible Markup Language. A standard for building markup languages.

XML application: A markup language created with XML.

XML declaration: The processing instruction that identifies a document as an XML document and
contains the version attribute and the optional standalone and encoding attributes. An XML declaration is
the first line in an XML document.

XSLT: Extensible Stylesheet Language Transformations. An XML application that defines how an XML
document will be transformed from one form of XML to another. XSLT is commonly used to transform
XML data to HTML for rendering on a client.

Putting XML in a form or page


A form is a perfect vehicle for XML. You can enter the XML tags, and include fields within the tags for
data. The result is an XML document with data that is meaningful when delivered to an XML parser.

You can also put XML on a page. A page in Domino Designer is a database design element that displays
information. You can use a page for traditional application content, such as a home page, or you can use
XML tags to describe the data on a page. As you will see in the section on using XML in a view, a page is
useful for embedding a view and adding the required XML tags to process the view. A page is also useful
for creating an extensible stylesheet (XSL) or a cascading style sheet (CSS) to direct a server or browser
on how to format data described with XML tags.

Defining data on a form with XML elements


When you use XML elements on a form or page, you must follow the rules for constructing valid XML
and you must properly format the XML tags.

Chapter 15. Including XML in Designer applications 317


XML tags look very much like HTML tags. There are some different rules for structuring the XML tags
that you must adhere to when marking up data. For example, requirements for nesting XML are more
rigid than those for nesting HTML tags. For information on marking data with XML tags, visit the IBM
XML Web site at http://www.ibm.com/xml

As an example of using XML on a form, the entries for each book in an online book catalog might look
like this:
<?xml version="1.0" encoding="UTF-8"?>
<BOOK>
<bookTitle>Chess for the Master</bookTitle>
<bookCategory>Games</bookCategory>
<bookAuthor>Alice B. Charles</bookAuthor>
<bookPrice>10</bookPrice>
<bookListPrice>12</bookListPrice>
<bookISBN>0-980-38475-81</bookISBN>
<bookDatePublished>April 1997</bookDatePublished>
<bookAbstract>The authority on all the latest chess moves, including the entire Big Blue arsenal.
</bookAbstract>
</BOOK>

Note: XML tags are case-sensitive. The tags <book>, <Book> and <BOOK> are all different. Opening and
closing tags must match case exactly for the XML to be well-formed.

To create documents in XML format


1. Create a new form or page.
2. Enter the document type declaration -- that is:
<?xml version="1.0" ?>
You can optionally add an encoding reference -- such as:
<?xml version="1.0" encoding="UTF-8" ?>
3. Enter the XML elements, generally a root element with sub elements.
4. Enter the fields that will hold the data you are marking with XML.
5. Choose Design - Form Properties.
6. On the Form Info tab, choose ″Render pass through HTML in Notes.″
This property tells Domino to pass all of the document text to the HTTP requester without generating
HTML tags.
7. Save and close the form.
8. To view the documents created from the form, create a view that uses a form formula that resolves to
the name of the XML form.

Formatting XML data with stylesheets


One of the attributes of XML is that it only describes data, and says nothing about the presentation of the
data. The presentation is not important on computer-to-computer transactions -- it only matters if you are
presenting the data to a user -- for example by posting it on a Web site. XML documents typically rely on
a stylesheet to determine the layout and presentation of the data. Some browsers provide simple default
styles for popular elements such as <Para>, <List>, and <Item>, but generally you must use a stylesheet
to describe the data format. There are two types of stylesheets you can use with XML:
v An extensible stylesheet language (XSL) describes how to transform XML into HTML or into another
version of XML.
v A cascading stylesheet (CSS) styles XML directly on Web browsers that support CSS.

318 Application Development with Domino Designer 7


To use a stylesheet, insert the stylesheet reference tag immediately after the document type declaration
and before the root element. For example:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="bookdisplay.css"?>
<BOOK>

If you create a stylesheet on a page, set the page property to ″Treat page contents as HTML.″

An XSL stylesheet that transforms information on books to HTML might look something like this:
<?xml version="1.0" ?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl" >
<xsl:template pattern="BOOK">
<HTML>
<HEAD>
<TITLE><xsl:value-of select="BOOKTITLE" /></TITLE>
</HEAD>
<BODY bgcolor="F0FFF8">
<B><xsl:value-of select="BOOKAUTHOR"/></B>
</BODY>
</HTML>
</xsl:template>
</xsl:stylesheet>
<?xml:stylesheet type="text/xsl" href="/roibooks.nsf/bookform.xsl"?>

A cascading stylesheet (CSS), instead of transforming XML into HTML, provides instructions directly to
the server regarding how to format each XML element. A CSS for books might look like this:
BOOK {
display: block;
border: 1px solid #cccccc;
}
BOOKTITLE {
display: block;
float: left;
margin-right: 10px;
padding: 5px;
}
BOOKAUTHOR {
display: block;
font-style: italic;
}

Using a view to generate XML


Views enable you to control which documents are rendered in XML and to track information and convert
it into XML for distribution across an intranet or the World Wide Web. You can find the view described
in this section in the ROI Books application on the Lotus Web site at http://www.lotus.com/xml.

Mapping XML tags to a view


In order to produce XML using a view, you have to map the XML tags from your DTD to the columns in
the view. Once you have created a view and mapped the XML tags to it, you embed the view into a

Chapter 15. Including XML in Designer applications 319


page. A view embedded into a page maintains the same functionality on the Web as a view in a Notes
client application and allows you to control the size and appearance of the view display. For views
displaying XML, the page contains the XML declaration and root element.

Example
The ROI Books application assigns each element and field in a document to a column in the XMLView
using a column formula. The column formula for the first child element also contains the open parent
tag, and column formula for the last child element contains the close parent tag. For example, the column
formula for the first column is:
"<BOOK><BOOKTITLE>"+bookTitle+"</BOOKTITLE>"

The parent element is <BOOK>, the child element is <BOOKTITLE>, and bookTitle is the name of the
field containing the content of the <BOOKTITLE> tag. There are more child elements within <BOOK>
that are included in this view, so the <BOOK> element is not closed until the last child element is added.
In the ROI Books application, the last child element is assigned to the last column of the view. The
formula for the last column is:
"<BOOKPUBLISHDATE>"+bookDatePublished+"</BOOKPUBLISHDATE></BOOK>"

The XML View is embedded into a page that contains the XML declaration and the root element
<BOOKCATALOG>.

To map XML to a view


1. Create a view and open it.
2. Select Edit - Properties to open the View Properties box.
3. Click the Advanced tab
4. In For Web Access, select ″Treat view contents as HTML.″ Domino generates HTML for the contents
of a view if this property is not selected. In addition, the contents of a view that is embedded into a
page are not visible if this property is not selected.
5. Click ″View Selection″ on the Objects tab and add a selection formula to define which documents will
be included in the view. For example, an application for an online bookstore contains a view for
approved orders. Documents are selected for the view using the following formula:
SELECT status="Approved"
6. Click ″Form Formula″ on the Objects tab and enter a formula that selects your template form.
7. Add columns to the view.
8. Click the first column of the view.

320 Application Development with Domino Designer 7


9. Enter a column formula in the Script area using the following syntax.
″<PARENT><CHILD>″+fieldname+″<\CHILD>″ If you have more than one element for any column,
add a semicolon (;) at the end of the first column formula and add the column formula for the next
element below it. ″<PARENT><CHILD>″+fieldname+″<\CHILD>″; ″<CHILD>″+fieldname+″<\CHILD>″;
″<CHILD>″+fieldname+″<\CHILD>″

Tip: Use the following syntax to make a field an attribute of an element. ″<CHILD
attributeName=\″″+fieldname+″\″>″+fieldname2+″</CHILD>
1. Click the second column and type a column formula into the Script area using the syntax below.
″<CHILD>″+fieldname+″<\CHILD>″
2. Repeat Step 10 for each XML element except the last one.
3. For the last child element, the use the syntax below.
″<LASTCHILD>″+fieldname+″<\LASTCHILD></PARENT>″

Embedding a view in a page


1. Open or create a page.
2. Select Design - Page Properties.
3. Click the Page Info tab.
4. In Web Access, select ″Treat page contents as HTML,″ and close the Page properties box.
5. Type an XML declaration above the place where you want the embedded view to display.
6. Place the cursor where you want the embedded view to display.
7. Select Create - Embedded Element - View.
8. (Optional) If you don’t want to display the same view in all circumstances, click ″Choose a View
based on a formula.″ When you click OK to close the dialog box, write a formula in the
Programmer’s pane to display the appropriate view.
9. (Optional) Click the embedded view and select Element - View Properties to change the alignment,
or style, or to hide the element under certain conditions.
10. Type a close root tag below the view.

To delete an embedded view, click the embedded view in the Work pane and select Edit - Clear.

Using an agent to generate XML


One of the biggest advantages of using an agent to generate XML is flexibility. Agents can be set to run
on a schedule, based on an event, or in response to a URL command. This kind of flexibility is necessary
to create automated XML applications. For example, the Web site for a bookstore contains a database
where customers contribute articles to the monthly newsletter. There is an editing and approval workflow
process that moves the articles through the system until they have been approved. An agent runs each
hour to collect the articles that are ready for publication and converts them into XML. The agent then
places the articles into another database as static XML documents where they are collected by subscribers.

The ROI Books application contains an agent called createXML which generates XML for each document
in a view and sends it out based on a request from a browser or a server. To see the output of this agent,
open the ROI Books application in Microsoft Internet Explorer 5 and click the XML Agent link, or run the
agent using the OpenAgent URL command:
http://host/roiBooks.nsf/createXML?OpenAgent

Chapter 15. Including XML in Designer applications 321


The agent could be written to not only print the output, but also to store XML output in a string variable
and write it to a static XML document or to another database system using LS:DO or the DECS connector
APIs.

Example: XML Agent


This example is a LotusScript agent that retrieves each document in a view called XML, creates XML
from the content, and prints the output.
Dim s As New NotesSession
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim view As NotesView

Set db = s.currentDatabase
Set view = db.GetView( "XML" )
Set doc = view.GetFirstDocument

Print "Content-type: text/xml"


’Prevents Domino from sending default headers.
Print "<BOOKCATALOG>"
’BOOKCATALOG is the root element of the XML document.
While Not ( doc Is Nothing )
’Loop as long as there are document objects available.
Print "<BOOK>"
’Send the parent element for each book document.
Print "<bookTitle>"+doc.bookTitle(0)+"</bookTitle>"
Print "<bookAuthor>"+doc.bookAuthor(0)+"</bookAuthor>"
Print "<bookPrice>"+doc.bookDiscountPrice(0)+"</bookPrice>"
Print "<bookCategory>"+doc.bookCategory(0)+"</bookCategory>"
Print "</BOOK>"
’Close the book element tag.
Set doc = view.GetNextDocument( doc )
’Get the next document in the view.
Wend
Print "</BOOKCATALOG>"
’Closes the root element.

322 Application Development with Domino Designer 7


Using a Java servlet to generate XML
Servlets are Java programs that run in response to a request from a Web browser. Unlike agents, servlets
load when the Web server starts up and stay resident on a server. They are commonly used for
generating and updating Web pages dynamically and for exchanging data between different applications.
You can extend the power of servlets to bridge applications by using XML as a common language
between applications. Not only can a Java servlet produce and deliver XML tags to the server for
processing, a servlet can also interact with the LotusXSL processor to format the data described by the
XML tags. XML in conjunction with XSL provides you with a powerful tool for customizing the transfer
of data.

Examples of XML servlet applications


As an example of how a servlet can leverage XML to deliver a customized package of data, consider an
organization where field sales representatives download information from a Domino database using a
variety of devices, such as a Notes client, a browser, or a PDA. A sales representative can request all of
the information pertaining to a particular client from the Domino application. A servlet assembles the
information from a variety of data sources, and packages the data with the appropriate XML tags. The
servlet can also use the LotusXSL processor to apply styles to the XML-tagged data and deliver the data
in the format best suited to the connecting device. In this scenario, the sales representative connecting
with a PDA on a low-bandwidth phone line will get less information than the sales representative
connecting with a Notes client running on a high-bandwidth network connection.

The following graphic shows the relationship between the connecting devices, the Domino application
running the servlet, and the back-end databases:

In another example of how a servlet can supply meaningful, customized data, consider a real estate
application with data on houses for sale stored in a Domino database. A real estate agent or a potential
buyer uses a Web browser to request information about property for sale from the Domino application.
The user specifies search criteria, such as the desired number of bedrooms. A servlet runs in the Domino
application, finding and assembling all of the documents that match the specified criteria. The servlet
dynamically wraps the data it finds in the correct XML tags -- such as <HOUSE> and <HOUSETYPE>. It

Chapter 15. Including XML in Designer applications 323


then uses the LotusXSL processor to apply styles from an XSL stylesheet and transforms the XML-tagged
data to HTML, pushing the correctly formatted data to the requesting browser.

Creating and using a servlet


You can either create a servlet from scratch, refer to an existing servlet by its URL, or use a pre-built
servlet. Each time you modify a servlet, you must restart the server to see the changes. Running a servlet
involves writing the servlet, enabling servlet support in Domino, and, if necessary, setting servlet
properties.

For general information on Java servlets, visit the Sun Microsystems site at http://www.java.sun.com

Including XML in a servlet


To include XML tags in a Java servlet, you need the LotusXSL Processor. You can download the LotusXSL
Processor from the IBM AlphaWorks site, at http://alphaworks.ibm.com/formula/LotusXSL

Viewing the XML in an application with DXL utilities


In addition to including XML in a Designer application, you can view all of the design elements
represented in XML using Domino XML (DXL). You can either view the XML in Designer, or you can
export the XML to a text file, where you can view it or edit it using your favorite editor.

For detailed information about DXL, refer to the Programming Guide.

Accessing design elements in XML provides you with the means of accessing the data in your application
and comparing it to or integrating it with other data sources that support XML. The DXL utilities can be
a very flexible alternative to generating reports on application elements using the Design Synopsis. You
can examine the DXL for a collection of elements, or you can transform it using an XSL file to apply
styles and formats that make your data more meaningful to you.

In order to transform DXL, you must construct an XSL file which processes the tags that make up a
design element. For example, the sample XSL file ″Report--AllLSinForm.xsl″ selects certain parts of the
DXL document and ignores others. The selected pieces (all relating to LotusScript) are reformatted to
make the output more readable.

Note: This feature requires Internet Explorer version 5.01 or later.

To view the XML for a design element


1. Check that you are running Internet Explorer version 5.01 or later.
2. Check your location document to make sure your Internet Browser field is set to ″Notes with Internet
Explorer″ or ″Internet Explorer.″
3. Select one or more design element in the design pane.
4. Choose Tools - DXL Utilities - Viewer.
Designer displays the XML for the design elements in the Notes client.

To export the XML for one or more design elements to a text file
1. Select one or more design elements in the design pane.
2. Choose Tools - DXL Utilities - Exporter.
3. Enter a file name and path for the XML file and click Save.

You can open the file in your favorite text editor and view or edit the XML source.

324 Application Development with Domino Designer 7


To transform the XML for one or more design elements using an XSL
1. Select one or more design element sin the design pane.
2. Choose Tools - DXL Utilities - Transformer.
3. Select the name of an XSL file to use for transforming the XML.
Designer ships with some sample XSL files that you can select or you can browse the file system to
select another XSL file.
4. Choose a type of output. Either select screen for a screen display, or specify an output file name.

Chapter 15. Including XML in Designer applications 325


326 Application Development with Domino Designer 7
Chapter 16. Including OLE objects in applications
Using Object Linking and Embedding (OLE) and OLE tools lets you extend the capability of Designer.
OLE technology lets you integrate data from other applications, such as spreadsheets, graphics tools, and
other data sources, into your application.

For information on scripting OLE objects and using OLE custom controls, see the Programming Guide.

Note: Some of the OLE technologies available in Notes/Domino are platform-dependent. Windows offers
the greatest range of options for sharing information and launching objects. Unless otherwise noted,
activities covered in this chapter apply only to Windows.

Using OLE and OLE-related tools in Designer, you can:


v Link and embed objects in forms
Using object linking and embedding (OLE), you can design a form that displays the same object in
every document created from that form. When you link an object, every document created from the
form refers to the source of the link. When you embed an object, the object itself appears on every
document created from the form. Linking and embedding objects is supported for Notes applications
only.
v Launch objects automatically
Using object linking and embedding, you can design a form that automatically launches an embedded
object or a new object created using any OLE desktop application. The autolaunch can occur when
users create, edit, or read a document based on the form. Autolaunch helps create a smooth workflow
involving multiple applications. It also allows users who are familiar with other products to work
within those applications without leaving the Notes application. This autolaunch feature is not
available for Web applications.
v Add custom controls to a form
If you use Notes with Windows and have OLE custom controls installed, you can create custom control
objects in documents or on forms. An OLE custom control, also known as OCX or as ActiveX, is a
small, self-contained software module with its own data. Your organization may create OLE custom
controls from various manufacturers and use the controls in Notes. Some OLE custom controls may not
provide online Help for their application.
v Set up forms to exchange field information with other Notes documents
You can create forms in Designer that automatically share information with documents created in other
OLE applications. Then, when users modify the contents of a field in a Notes document, the changes
are automatically made to the corresponding fields in the other application’s document. Data exchange
can occur in both directions: users can edit fields in Notes or the other application, and the
modifications are automatically exchanged. OLE applications must support NotesFX in order to use
field exchange in Notes. Field exchange is not available for Web applications.
v Publish an action
This is the most powerful of the OLE-based tools because it is the most flexible. You can automate
complicated or repetitive tasks that involve multiple operations across multiple applications. You
design an action using formulas or scripts, and then publish it. The action appears on the Action menu
in any Notes/FX 2.0-enabled application. This feature is not available for Web applications.

Linking and embedding objects in forms


When you link or embed an object in a form, every document created from the form displays the object.
Whether you link or embed an object depends on how the form will be used.

327
Linking maintains the object in the source application and displays the object in the host application,
which in this case is the Notes form. For example, a form might contain a Lotus 1-2-3® spreadsheet that
you update frequently. The advantage to linking is that you can maintain control over the source. When
you update the object in the source application, all links to the object automatically update. The
disadvantage to linking is that all users must have access to the file containing the object, as well as the
application used to create it. In this example, the users need the spreadsheet file and 1-2-3.

Embedding an object allows you to place the object in a form. The object ″lives″ in the form, and users
can modify and update the object from the form. For example, if you embed a graphic in a form, users
need a compatible version of the source application to view the graphic. Designer access is required to
modify the graphic.

OLE and LotusScript


To build on the power of OLE, use LotusScript to create or enhance workflow applications. You can use
LotusScript to create, manage, and update objects within Notes documents.

For more information on using LotusScript with OLE objects, see the Programming Guide.

To link an object in a form


To link to an object, it must already exist in the source application.
1. Use a source application that supports object linking and embedding (OLE) to create an object.
2. Copy the data in the application to the Clipboard.
3. Open the form in Designer, click where you want the object to appear, and choose Edit - Paste
Special. Then choose ″Paste Link to Source″ and click OK.
4. Save and close the form.

To embed an object in a form


You can create an embedded object from within Designer.
1. Click where you want the object to appear on the form, and then choose Create - Object. Designer
lists the available applications that support OLE under ″Object type.″
2. Choose an application. Designer will launch the application ″in-place″ by default if the application
supports this; otherwise, Designer will open the application.
3. Create data in the application.
4. If you are using ″in-place″ editing, click outside the OLE application to return the focus to Designer. If
Designer originally opened the application, exit the application.
5. Save and close the form.
For more information on creating and editing objects, see Notes Client Help.

Adding OLE custom controls to a form


An OLE custom control, also known as OCX or as ActiveX, is a small, self-contained software module
with its own data. You can add a custom control to a form to make the control available in documents
created from the form. After inserting the control, you can edit properties that control its display.

To create an OLE custom control object


1. In a rich text field or on a form, choose Create - Object.
2. Do one of the following:
v Select ″Create new Object.″ In the Object type list, choose a custom control. The custom controls
have starburst icons next to them.
v Select ″Create new Control.″ In the Object type list, choose a custom control.

328 Application Development with Domino Designer 7


3. Click OK.
Notice after you embed a custom control that the properties for the control appear below in the
Programmer’s pane. By default these properties are listed alphabetically. The number of properties
available depends on what the specific control supports. Some controls will support dozens of
properties, others just a few. You will always see at least the standard eight Notes properties while in
a form.

Tip: Use the ″Remove Control from List″ and ″Add Control to List″ buttons to maintain the list of
custom controls that display in the Object type box.

Note: Some custom controls do not display in the Create Object dialog box. You cannot use this method
to insert these controls. Instead, use LotusScript to insert them because these types of controls do not
support a user interface and are only programmable.

To access an existing control, select it.

When a custom control is active, the Help menu is a combination of Designer (File and Applet) and the
custom control. The control may include one menu item for itself -- for example, ″Spreadsheet″ for a
spreadsheet control -- and Help. The control’s Help is substituted for Designer Help.

Use the Applet menu choice to:


v Copy and cut the entire object. (Use the Edit menu to copy and cut selected text in the object.)
v Access Notes properties for the control, including the name of the control.
v Access the control’s own properties.
v Set the control’s mode.
v Freeze and unfreeze the control’s events.

If a control is active when you embed it in a form, a list of properties and event appears in the Info List
of the Programmer’s pane. You can attach scripts to these events.

For information on attaching scripts to a custom control, see the Programming Guide.

Troubleshooting tips for OLE and Active X objects


Sometimes when embedding an OLE object or ActiveX control you might receive the following error:
An error has occurred while processing a request on an object

This error message might mean one of the following:


v You are trying to embed an ActiveX control which does not support being inserted manually (the
control can only be embedded programmatically). Check the Windows registry to see if the control
supports being inserted (embedded); if the control is listed under the \\HKey_classes_root, verify that
the ″Insertable″ key appears under the control’s name.
v You are trying to embed an OLE object or ActiveX control which has not been installed correctly or the
Windows registry contains conflicting information about the OLE object or ActiveX control. Reinstall
the OLE object or ActiveX control to resolve the issue.
v You may have multiple versions of Notes installed. For OLE to work properly, the Windows registry
must be accurate. Make sure you are using the most recently installed version of Notes.
v Your system is low on memory. Close your applications and restart your computer.

Chapter 16. Including OLE objects in applications 329


Modifying a form to size an embedded object
If an object’s server application supports OLE2 ″in-place″ editing, Designer can expand the object when
you edit it so that you can edit the object directly from the form or page. You can edit the property for
the OLE object using either the Object Properties box, or using the property sheet in the Programmer’s
pane.

To edit the OLE object using the properties box


1. With the form in Edit mode, click the object.
2. Choose Edit - Properties or select the dynamic menu presented for the OLE application. For example,
clicking a Lotus 1-2-3 object adds the menu choice ″Workbook.″ Select Workbook, then Object
Properties.
3. In the Properties box, choose ″Size object to fit window.″ The following occurs:
v When a user uses this form to create a document, the user must double-click the object to display it
in the full application window.
v If the document contains information below the object, the user will not be able to see that
information.
4. Close the Properties box.
5. Save and close the form.

To edit the OLE object using the properties in the programmer’s pane
1. With the form in Edit mode, click the object.
Properties for the OLE application display in the Programmer’s pane.
2. Highlight (SizeToWindow) and double-click the value to toggle it from FALSE to TRUE. Click outside
the Programmer’s pane to accept the change.
3. Save and close the form.

Note: When the SizeToWindow property is set to TRUE, an OLE object will expand to fit the entire
window after a user double-clicks it. Note that if there is information on the form other than the OLE
object, it will not display when the OLE object is expanded to fit the window.

Modifying a form so that it sizes an OLE custom control


You can edit the size properties for an OLE custom control using the properties box for the object or by
setting property values in the Programmer’s pane.

To edit the OLE custom control using the properties box


1. Open the form and click the custom control.
2. Choose Applet - Object Properties.
3. Choose one of the following in the properties box:
v ″Size object to window.″
v ″Size object below field.″
4. Close the properties box.
5. Save and close the form.

To edit the OLE custom control in the Programmer’s pane


1. Open the form and click the OLE custom control. Properties for the custom control OLE application
display in the Programmer’s pane.
2. Select ″SizeToWindow″ and double-click the value to toggle it to TRUE.

330 Application Development with Domino Designer 7


3. Click outside the properties sheet to accept the change.
4. Save and close the form.

Expansion properties of OLE custom controls


When you use the form to create a document, the control expands, based on the property you chose.
Note the following:
v The property you chose takes effect after you save and close the form or document.
v If you chose ″Size object to window,″ the following occurs:
– When a user creates a document or opens an existing document in Edit mode, the custom control
automatically expands to fill the entire application window.
– If the document contains information below the custom control, the user cannot view that
information while the custom control is expanded.
v If you chose ″Size object below field,″ the following occurs:
– When a user creates a document or opens an existing document in Edit mode, the custom control
automatically expands to fill the area of the Notes window below the layout region. If the document
does not contain a layout region, the custom control expands to fill the entire application window.
– If the document contains information below the layout region, the user cannot see that information
while the custom control is expanded.
– If the document contains two or more layout regions, the custom control expands below the first
layout region. The user cannot see the other layout regions.

Modifying a form to run a custom control in Read mode


This option is available only for custom controls. Some custom controls do not render anything for
display in Read mode. With this setting, you can force the custom control to display in Read mode.
1. Open the form and click the custom control.
2. Choose Edit - Properties or Applet - Object Properties.
3. Choose ″Run object when reading document″ in the properties box.
4. Close the properties box.
5. Save and close the form.

When a user opens a document, the object automatically launches in Read mode. The user can change
the object and print the changes, but cannot save the changes without first putting the document into
Edit mode.

Updating objects by document


You can create an object or custom control in a form and let documents created with the form update the
object or custom control. A user can change the OLE object or custom control and save those changes
with the document. The OLE object or custom control in the form does not overwrite the revised OLE
object or custom control in the document.

To modify properties using the properties box


1. Open the form and click the object or custom control.
2. Choose Edit - Properties.
3. In the properties box, choose ″Update object from document.″
4. Close the properties box.
5. Save and close the form.

Chapter 16. Including OLE objects in applications 331


To modify properties using the properties sheet in the Programmer’s
pane
1. Open the form and click the object or custom control. The properties for the object or control display
in the Programmer’s pane.
2. Select the property UpdateFromDocument and double-click to toggle the value to TRUE.
3. Save and close the form.

Launching objects automatically


You can have a form automatically launch (autolaunch) an embedded OLE object or a new OLE object
when a user creates a document or opens one for reading or editing. A new OLE object is one that is
blank until users add data.

Note: Autolaunching is not supported with custom controls (ActiveX controls) or for Web applications.

The user can change the embedded object and add data to a new object directly in the application that
created the object. The Notes document automatically displays the changes.

When you design a form that autolaunches an embedded object, the object must be the first OLE object
in the form. To autolaunch other objects embedded in the form, you must write a script. Users can launch
embedded objects manually, except in documents that open as modal dialog boxes.

If you create an object in a rich text field on a form, when users create a document, the object launches. If
you don’t create the object in a rich text field, when users create a document, Notes launches the first
object that appears in the form. When users subsequently open the document for reading or editing, the
first object in the document launches.

The following are ways to launch OLE objects:

Launch an object automatically


The object can be a spreadsheet, a word-processing document, a graphic presentation, a database, or a
multimedia object. You can autolaunch objects created in any registered OLE application.

Launch a new object automatically


A new object is blank until users add data. You can autolaunch a new object in any registered OLE
application.

Launch an object in-place or out-of-place


The object launches in-place if it launches within the Notes document. The object launches out-of-place if
it launches in the application that created it.

Define the conditions under which objects are launched


The object launches only when it is created or when it is opened in Read or Edit mode.

Use the form open in a modal dialog box to create documents


The object launches into a modal dialog box that the designer uses to specify actions users can take with
the object.

Hide the Notes document


You can hide the Notes document when the object is launched or when the launched object is closed.

332 Application Development with Domino Designer 7


Hide the original embedded object in documents
You can hide the original embedded object and display only the most recent, updated version of the
object in a document.

Designing forms that launch objects automatically


You can create forms that automatically launch an embedded object when a document is created. The
object can be either:
v An existing embedded object, that is stored and launched from a rich text field
v A new object that is created and then stored in a rich text field.

When an object is autolaunched, modified by the user, and saved, it is displayed in the document in the
field you specify in the ″Create object in field″ box. You can specify ″First Rich Text Field″ to display the
saved object in the first rich text field in the document.

To display the current representation of an existing object in the document, store the form with the
document. This causes updates to the object to replace the original embedded object in the document. Be
aware, however, that storing the form with the document uses a large amount of disk space and
processing time.

Objects and full text search


Full text searches can include embedded objects and attachments. When a full text search finds a match
in an embedded object or attachment, the object or attachment opens, but the matching word or phrase
does not appear highlighted.

Nested objects
If the OLE server application is also a client application, an object in a Notes document may have other
objects within it. In this case, when an object is updated, the object in the Notes document reflects the
changes even if they were made in an other application.

When an object that contains other objects is autolaunched, only the application that created the object
embedded in the Notes document is launched.

To design a form that launches an existing object


1. Open the form containing the embedded object you want to launch automatically.
2. Choose Design - Form Properties.
3. Click the Launch tab.
4. Select ″First OLE object″ in the Auto Launch box.
5. (Optional) To create the object in a rich text field, do the following:
v Position the insertion point where you want to create a field to display the object, and choose
Create - Field.
v Enter a name for the field.
v Select Rich Text in the Type box.
v Select Form in the ″Properties for″ drop-down list.
v Click the Launch tab.
v Select the name of the rich text field in the ″Create object in field″ box or choose ″First Rich Text
Field.″
v Select ″None″ if you do not want to display a current representation of the object in documents.
6. (Optional) To store the form with the document choose Design - Form Properties, then click the
Defaults tab, and select ″Store form in document.″
7. Close and save the form.

Chapter 16. Including OLE objects in applications 333


Launching an object ″in-place″ or ″out-of-place″
By default, objects are launched ″in-place,″ so that the object can be edited right in Notes. If the object
does not support ″in-place″ editing, then the object will be launched ″out-of-place,″ so that focus shifts to
the application used to create the object and Notes goes into the background.

Only applications that support OLE2 can launch objects ″in-place.″ Applications that support OLE1
always launch ″out-of-place,″ regardless of the ″Launch in place″ property.

Objects that are embedded in the form as icons always launch ″out-of-place.″

Note: Autolaunching is not supported on the Macintosh.


1. Open the form containing the object.
2. Choose Design - Form Properties.
3. Click the Launch tab.
4. Select ″Launch in place,″ or deselect it to launch ″out-of-place.″
5. Close and save the form.

Specifying the event that causes an object to autolaunch


You can design a form so that an object autolaunches when a user creates, edits, and/or reads the
document. A new object autolaunches when a user creates a document. By default, existing objects
autolaunch each time a user reads or edits a document containing an object.

Autolaunching new objects


You can control whether the object in the first rich text field in a form autolaunches when a document is
created, edited, or opened. If the form you’re designing autolaunches a new object, make sure the
″Launch when″ setting includes ″Creating,″ because this is the only event that launches a new object.
After the user creates the document, the new object is saved with the document. Other ″Launch when″
settings, such as ″Reading″ or ″Editing,″ take effect when a user subsequently opens the document.

Making settings compatible


If you set the form to ″Automatically enable Edit mode″ (on the Form Defaults tab of the Form Properties
box), make sure the ″Launch when″ settings are compatible. For example, if you design the form so that
the object launches only when users open the document in Read mode and you set the document to
enable Edit mode automatically, the document always opens in Edit mode and the object never
autolaunches.

To specify the event for autolaunching


1. Open the form containing the object.
2. Choose Design - Form Properties.
3. Click the Launch tab.
4. Select Creating, Editing, and/or Reading in the ″Launch when″ box.
5. Close and save the form.

Examples of specifying the event for autolaunching


Design a form to distribute financial information contained in a 1-2-3 object. In the form, you embed a
1-2-3 object that is a template for entering financial information. Create a rich text field in the form, and
specify that the field display the object. Also specify that the object autolaunch only when a user uses the
form to create a document.

When a user uses the form to create a document, the 1-2-3 object autolaunches so the user enters the
information in 1-2-3. The user closes and saves the 1-2-3 object, and then closes and saves the new

334 Application Development with Domino Designer 7


document. When people read the document, the 1-2-3 object is visible in the rich text field, but the object
does not autolaunch. To edit the object, the user opens the document in Edit mode and double-clicks the
object to launch it.

Designing a form that launches an object from modal dialog boxes


You can design the form that launches an object to open as a dialog box. When users create or open a
document that opens in a dialog box, they cannot access Notes menus. Instead, users can:
v Enter or modify data
v Launch the first embedded OLE object by clicking a Launch button on the dialog box
v Choose a command from the Action menu at the bottom of the dialog box

To set objects to open as a dialog box


1. Open the form.
2. Choose Design - Form Properties.
3. Click the Launch tab.
4. Select ″First OLE object″ or a server application from the Auto Launch drop-down list.
The list includes all registered OLE server applications on your hard drive as well as ″First OLE
object″ to launch the first OLE object on your form. You cannot design the form to open as a dialog
box if you select the ″First Attachment,″ ″First URL″ or ″First Document Link″ objects.
5. Select ″Present document as modal dialog.″
6. Close and save the form.

Tip: The Hide-When section allows you to decide when to show the modal dialog. You have six options
to hide the modal dialog: ″Opening create,″ ″Opening edit,″ ″Opening read,″ ″Closing Create,″ ″Closing
edit,″ and ″Closing read.″

For more information about showing form actions, see the chapter ″Adding Automation to Applications.″

Designing a form to hide the Notes document


To allow users to move seamlessly from the Notes view level to an autolaunched application and back
again, design a form to hide the Notes document.

When you can hide the Notes document


You can design a form to hide the Notes document when users:
v Create a document (Opening Create).
v Open a document to edit it (Opening Edit).
v Open a document to read it (Opening Read).
v Close a document after creating it (Closing Create). This option is available only if ″Opening Create″ is
selected.
v Close a document after editing it (Closing Edit). This option is available only if ″Opening Edit″ is
selected.
v Close a document after reading it (Closing Read). This option is available only if ″Opening Read″ is
selected.

Mixing Hide/Show options


You can also design a form that hides the Notes document in some circumstances and shows it in others.
Use this type of form when document creators, editors, and readers play different roles in maintaining
the information in the Notes database.

Hide Notes documents when:

Chapter 16. Including OLE objects in applications 335


v The main focus of the document is the object, and users don’t need to fill in anything else.
v The form contains only one object.
v Users aren’t familiar with Notes and want to work in a familiar application.
v The Notes database is functioning solely as a container system for other application files.
v All users have access to and can launch the other application and always work in that application.

Show Notes documents when:


v Readers need to see more than the data object itself.
v The form contains multiple objects.
v Revising the data in the object is optional; therefore, you don’t need to launch the application every
time the Notes document opens.
v Users who create and edit documents need to fill in other fields on the form.
v Some users have operating systems, such as OS/2, that don’t support OLE objects, but they still need
to read the information or edit other fields in the Notes document.

To hide a Notes document


1. Open the form.
2. Choose Design - Form Properties.
3. Click the Launch tab.
4. In the ″Hide when″ list, select an option. (Click the option again to deselect it.)
5. Close and save the form.

Example
You create a report-tracking database that allows users to use 1-2-3 to create and update their own
expense reports. When users create or update expense reports, they don’t need to see the Notes
document; instead, they want to autolaunch the expense report object in 1-2-3.

To design a form that mirrors your users’ workflow, create an Expense Report form, embed a worksheet
object in the form, and set the form properties to automatically launch the worksheet. In the ″Hide when″
box, select:
v Opening Create
v Closing Create
v Opening Edit
v Closing Edit.

When users choose Create - Expense Report, Notes automatically starts 1-2-3 and launches the embedded
worksheet object. Users enter information directly into the 1-2-3 worksheet object and never see the Notes
document. When users complete the expense reports and quit 1-2-3, the worksheet object embedded in
the form updates, users are returned to the view level in Notes. If users want to edit their expense
reports, they open the document in Edit mode, and 1-2-3 autolaunches. When they close 1-2-3, users are
returned to the view level of Notes.

Information from the expense report worksheet appears in the Notes document or in the Notes view. The
Notes database contains all of the expense reports.

336 Application Development with Domino Designer 7


Hiding an embedded object in a document
You embed an object in a form for autolaunch so that users can make modifications to the object. You
then specify a rich text field to display the latest representation of the object. If you want to display only
the latest version -- not the original version -- of the object, you must design the form to hide the original
embedded object. After the user makes changes to the object and returns to the document, only the
changed version appears in the document.
1. Open the form containing the object.
2. Select the object you want to hide.
3. Open the object’s properties box.
4. Click the Hide When tab.
5. Select one or more options for hiding the object.
6. Save and close the form.

Publishing actions
Actions allow you to integrate file creation and storage in other desktop products with the document
sharing, storage, security, and management tools of Notes. When you publish an action, you make it
available on the Action menu in any open OLE server application. For example, you might automate a
document review process so that a Notes user opens a document that autolaunches a Word Pro file. After
editing the file, the user clicks the ″Send to Next Reviewer″ menu choice in Word Pro, which routes the
document containing the Word Pro document to the next user. By publishing actions, you seamlessly
coordinate tasks between applications.

From a designer’s point of view, publishing actions expands the scope of what you can do with a flow of
work and enhances your ability to control that flow. Teamed with autolaunching, publishing actions
allows you to focus or limit user-access to commands, thereby controlling the flow of work. By
simplifying and automating multistep tasks, you improve the security of your system and reduce the
chance of user error. Actions can incorporate functions, @commands, and LotusScript. Notes also supplies
a number of simple actions, such as Move to Folder, which allow you to incorporate useful actions in
your form design without programming in LotusScript.

For information on actions, see ″Overview of Automation.″

When an action executes


On the Advanced (NotesFlow Publishing) tab of the Action Properties box, you can specify what happens
when an action runs. Select ″Close OLE object and return to Notes″ to close the object, save any changes
made during the OLE session, and return to Notes. Select ″OLE object remains open″ if you want the
focus to remain with the OLE object. This property is useful if users need to choose more than one action
before returning to Notes.

When designing actions, keep in mind the state of the application when returning to Notes. For example,
if you use the autolaunch feature with an action, decide whether you want users to return to Notes,
whether you want the Notes window hidden, whether users are in a document or a view, and whether
the document has been saved or is new. Write documentation or field help in the form to provide
guidance to users.

″Bring document window to front″ property


On the Advanced (NotesFlow Publishing) tab of the Action Properties box, choose the property ″Bring
document window to front″ if you want the focus to return to Notes without closing the OLE object. By
shifting the focus back to Notes, you provide the opportunity for user-input in Notes. When you use this
property, remember that the OLE object has not been saved, unless you explicitly saved the object as part
of the action. Therefore, you may have to provide a way for users to return to the object to save it.

Chapter 16. Including OLE objects in applications 337


Note: The ″Bring document window to front″ property applies only when the document window in
Notes has not been hidden.

To publish an action
1. Open the form.
2. Choose View - Action pane to display the Action pane.
3. Double-click the action you want to publish.
4. Choose Design - Action Properties.
5. Click the Advanced tab.
6. Select ″Publish Action with OLE object.″
7. Select a property that controls what happens after a user chooses an action.
8. (Optional) Select ″Bring document window to front″ to change the default setting.
9. Close and save the form.

For information about creating an action, see ″Adding Automation to Applications.″

Note: If actions do not get published even after you select ″Publish action with OLE object,″ make sure
Notes/FX ™ 2.0 is enabled. Choose Design - Form Properties and click the Defaults tab. The ″Disable
Field Exchange″ check box should be deselected.

Examples
A Word Pro document needs to be routed for approval. The Notes form you create has an embedded
Word Pro document set to autolaunch when edited and an action called ″Send to Next Reviewer.″ When
a user opens the Notes document in Edit mode, the Word Pro document automatically launches. After
reviewing the Word Pro document, the user selects the Send to Next Reviewer action from the Action
menu. This action sends the Notes document to the next reviewer and closes the object.

To provide other routing options, you can add the actions ″Ready for Next Reviewer,″ ″Return to
Previous Reviewer,″ and ″Archive Document″ to the Notes form.

Exchanging field data


Notes/FX is supported only for Notes applications. Using Notes/FX, you can design forms so that field
contents in an OLE server application file automatically appear in corresponding fields in a Notes
document, and vice-versa. Depending on the type of field, you can update the contents from Notes or
from the other OLE application.

To exchange data, there must be a one-to-one correspondence between the shared fields. Both the OLE
server application file and the Notes form must contain the same shared fields. A Notes/FX field can be:
v One-way
v Two-way
v User-defined

One-way fields
One-way fields provide information for exchange in only one direction. These fields supply information
about a file -- for example, file size and creation date. One-way fields exist by default in the OLE server
application; you must create the corresponding fields in your Notes form.

For example, Word Pro documents have a field called SizeInK, which contains the size of the Word Pro
document in kilobytes. To exchange the data in this field with a field in a Notes form, create a field
named ″SizeInK″ in the Notes form. After you set up field exchange, changes to the Word Pro field
appear in the Notes field; however, changes made to the Notes field do not affect the Word Pro field.
338 Application Development with Domino Designer 7
Two-way fields
Two-way fields provide information for exchange in two directions -- that is, from Notes to the OLE
application and from the OLE application to Notes. When you change the contents of the field in either
application, both fields update. Fields defined as two-way exist by default in many OLE server
application files; therefore you must create corresponding fields in your Notes form.

For example, the Document Description field in a Word Pro document corresponds to the Subject field in
a Notes document. After you set up field exchange, changes to one field automatically appear in the
other field. The fields must have the same name.

User-defined fields
These fields exchange data in two directions, but you must create these pairs of fields, since they do not
exist by default in the OLE server application file or in Notes. User-defined fields usually exchange
working data, such as text or numbers.

For more information about fields in OLE server applications that exchange data with Notes, see the
documentation for the OLE server application.

Preparing a form to exchange data


Data is exchanged on a field-by-field basis. Every Notes/FX 2.0 field in a Designer form must have a
corresponding field with the same name in the other application file.

Table of one-way and two-way field exchange


The following table lists one-way and two-way fields found in most Lotus applications. For a complete
list, see the documentation for the application.

Field name Data type Contents


LastRevisionDate Time Date and time the file was last revised
NumberOfEdits Number Total number of revisions to a file
EditingTime Number Total time the file was open
SizeInPages Number Number of pages in the file
SizeInK Number Size of the embedded object in kilobytes
DocumentClass Text OLE class name of the application embedded in Notes
Subject Text Description of the document
Categories Text (allow multi-values) Keywords that Notes uses to categorize documents

Note: If you are using a form copied from a Designer template, fields may already be set up for field
exchange.

To enable field exchange


1. Open the form and choose Design - Form Properties.
2. Click the Defaults tab.
3. Make sure ″Disable Field Exchange″ is deselected.
4. Close and save the form.

Note: You can disable Notes/FX 2.0 field exchange without removing the Notes/FX fields from the form
by checking the ″Disable Field Exchange″ property.

Chapter 16. Including OLE objects in applications 339


To set up field exchange
1. Open the application file.
2. Write down the name of each field you want to exchange and close the application.
3. In Designer, open the form you want to prepare for Notes/FX field exchange.
4. Embed the object containing the fields you want to exchange.
5. Choose Create - Field.
6. Give the field the same name as the corresponding field in the other application.
7. Close and save the form.

Example of exchanging data for an expense form


You create a form to file and distribute trip reports. The reports contain descriptions of the important
business aspects of the trip, as well as the total expenses. You record expenses in a Lotus 1-2-3 expense
report template. You want the total expenses of the trip to appear automatically in the Notes document.

In the 1-2-3 template, create an expense report. In one cell enter Total_Exp. Now create a range name for
this cell and name it Total_Exp. Because this is a custom Notes/FX field, you need to tell 1-2-3 to use this
range name for Notes/FX. Select File - Workbook Properties and then select the Notes/FX Fields tab.
Select the New Field button and then select the range name Total_Exp. Click OK twice. The row below
the cell entitled Total_Exp will hold the actual data that is exchanged between Notes and 1-2-3. Save and
close this 1-2-3 Workbook.

In Designer, create a form called ″Trip Report″ and embed the recently created 1-2-3 expense report. The
Trip Report form contains text fields for entering information about the trip. At the bottom of the form,
use the text ″The total expenses for the trip were:″ to label a field area and create a numeric field named
″Total_Exp″ which corresponds with the field name in the 1-2-3 expense report template.

340 Application Development with Domino Designer 7


When users use the form Trip Report to create reports and activate the 123 object to enter expenses, the
total expenses are automatically inserted back in the Trip report document.

Chapter 16. Including OLE objects in applications 341


342 Application Development with Domino Designer 7
Chapter 17. Creating a workflow application
Workflow applications let you automate tasks. These tasks most often involve automatically sending mail
messages or automatically routing documents, such as tracking orders and project plans to be reviewed.
All projects need one or more people to complete a series of tasks and can benefit from workflow
applications because they guide the project through these tasks automatically. Workflow applications
reduce overhead and errors, speed processes, and track the status of a project. For example, a workflow
application might automatically send a document in a publishing company from writer to editor to
proofreader to production. At each stage, an individual is responsible for specific tasks related to that
document. Once the task is complete, the workflow application ensures that the individuals responsible
for the next task are notified and receive the data they need to execute their part of the project.

Examples of workflow applications


The Document Library template (DOCLBW60.NTF) and the Teamroom template (TEAMRM60.NTF) are
examples of applications that include workflow features. For both templates, the document you want
reviewed is kept in a central database and is not mailed to reviewers. Reviewers receive mail notifying
them of the need to review a document. A doclink to the document is often included in the mail.

The Document Library template uses a review cycle so that you can route a document link to a series of
recipients. It allows serial and parallel reviews. With parallel reviews, every reviewer receives e-mail
notification at the same time. With serial reviews, reviewers comment on the document in a particular
sequence and receive e-mail notification only after the previous reviewer has completed the review.

The Teamroom template contains the following workflow features:


v Parallel review processing
v Automatic mailing and archiving of newsletters and memos
v Action item notifications, which send notices of new action items and reminders of past due items

See the Domino Designer Templates Guide for additional information on these templates.

Planning workflow
Before you select the type of mailing features that suit a workflow application, you should carefully plan
the actual workflow. One way to implement a workflow application is to collect information in a central,
shared database and then distribute the information through e-mail to the appropriate people. Another
way to implement a workflow application is to send documents automatically from one user to another
for review.

Central shared databases


Users working in a shared database can create and edit documents directly in the database. Remote users
must dial into the server database to contribute. Designers can implement automatic e-mail notifications
to alert users to documents needing their attention. The automatic e-mail notifications can be built into
forms or agents. To make it easier for users, the notifications often include document links. For remote
users, however, you might include a copy of the document within the e-mail notification instead of a link
to the document. For Web users, include a URL link in the e-mail notification.

Using central shared databases places the least burden on network resources and conserves server disk
space. Users also get to see each other’s review comments (if the form is set up that way). The
disadvantage of using central shared databases is that users need network access or remote access
through a modem.

343
Individual mail databases
If users work in individual mail databases, they can create and respond to documents and then route
them to each other or to a central mail-in database. Automated, easy-to-use forms that are stored in
documents are typical of such applications. Of course, if you are sending individual mail messages, you
are increasing disk space because the form is stored with the document.

Using individual mail databases makes it easier for remote users because they only need to access mail
instead of accessing mail and a remote database. The disadvantage of using individual mail databases is
that workflow process may take longer since work is done sequentially. Also, replication times may be
longer because of document size. Remote users should consider using replication or Domino Off-Line
Services (DOLS).

Setting up automatic mailing


To send automatic mail notices from a database, you can use forms or use form and view actions, agents,
and events.

Sending links to documents


In some workflow applications, you may want to mail notices of new or modified documents or
reminders of work that needs to be done. Sending a link to a document instead of sending the document
itself saves time and space. To send a link automatically, create an agent, event, form or view action,
hotspot, or button that includes one of the following:
v The simple action ″Send Mail Message″ with ″Include link to document″ selected.
v The simple action ″Send Newsletter Summary.″
v The formula function @MailSend with the [IncludeDocLink] flag.
v A LotusScript program that uses the Send method in either the NotesDocument class or the
NotesUIDocument class and the FormatMsgWithDoclinks method in the NotesNewsletter class.
v A Java program that uses the Send method in the lotus.notes.Document class and
FormatMsgWithDoclinks method in the lotus.notes.Newsletter class.

Sending documents
Sometimes it makes sense to mail documents automatically, as in the following situations:
v You want users to work on documents sequentially
v You want to send documents to a mail-in database for centralized tracking

For these applications, you must create a form with a SendTo field field that specifies the recipients, or
use a formula or program that includes the SendTo information.

Use any of these methods:


v Add a MailOptions field with a value of 1 to force the document to be mailed when it is saved.
v At the Defaults tab of the Form Properties box, select ″On Close: Present mail send dialog″ to let users
decide if they want to mail the document.
v Create an agent, event, form or view action, hotspot, or button that uses:
– The simple action ″Send Document″
– The formula functions @Command([MailSend]) for optional mailing or @MailSend for automatic
mailing
– A LotusScript program that uses the Send method of the NotesDocument class or the
NotesUIDocument class
– A Java program that uses the Send method of the lotus.notes.Document class

344 Application Development with Domino Designer 7


In addition, all forms and views contain the default action ″Send Document″ that you can display in the
Actions menu or the action bar.

For more information on reserved fields for mailing options, see the topic ″Reserved fields that control
mailing options″ in the chapter ″Designing Fields.″

Enabling users to view documents


To allow users to view workflow documents, do one of the following:
v Copy the form into the master mail template on the server and refresh the design of mail databases.
v Select the ″Store form in document″ option for the form.

Forwarding documents in a mail memo


Use mail forwarding to mail documents that don’t have a SendTo field. Create an agent, event, form or
view action, hotspot, or button that uses one of the following:
v The simple action ″Send Mail Message″ with the option ″Include copy of document″ selected
v The formula function @Command([MailForward])
v A LotusScript program that uses the Forward method in the NotesUIDocument class

In addition, all forms and views contain the default action ″Forward″ that you can display in the Actions
menu or the action bar.

Sending replies to a mail memo


To create an automatic reply to a mailed document, create an agent, event, form or view action, hotspot,
or button that uses the simple action ″Reply to Sender.″

Mailing features and Web applications


Web users whose mail databases reside on a Domino server can participate in mailing processes. When
you are designing forms or views, include form or view actions as alternatives to menus for tasks Web
users need to do. For example, you can create a ″Send Document″ action so that it appears on the action
bar of a form both in Notes and on the Web.

Displaying the Mail Send dialog box


If you want the Mail Send dialog box to appear so that users have the option of mailing, saving, signing,
or encrypting a document, do one of the following:
v Select ″On Close: Present mail send dialog″ in the Form Properties box on the Defaults tab.
v Write a formula that includes @Command([MailSend]).

Make sure that you include a SendTo field on the form.

Creating a database that receives mailings


If a database is designed to receive mail, you must create a Mail-In Database on a server that all users
and servers can access. Then, you must create an associated Mail-In Database document in the Domino
Directory. This document must exist in the Domino Directory of every server that stores a replica of the
database. The database cannot receive mail until you create this document.
1. In the access control list (ACL) of the Mail-In Database, make sure you have at least Author access
with the Create Documents privilege selected.
2. Open the Domino Directory and choose Create - Server - Mail-In Database.

Chapter 17. Creating a workflow application 345


3. Complete the following fields of the mail-in database document.

Field Description
Mail-in name A name that identifies the database in the SendTo fields or in formulas on the form.
Description A description of the database.
Domain The domain name if your organization uses multiple mailing domains.
Server The hierarchical name of the server on which this database resides.
Filename The database directory name (if the database is in a subdirectory of the Notes Data directory)
and the file name.

For information on all the fields in the Mail-in database document, see Lotus Domino Administrator
Help.
4. Optional) Click Administration. Next to Administrators, enter additional names of people who can
change this document.
5. Give the name of the database to appropriate users so they can enter it in the To field of messages
destined for the database.
6. Close and save the document.

Example of using an agent that sends automatic replies


For a mail-in Survey database, you can create an automatic response agent so employees receive a
confirmation that the survey arrived.
1. Select the Survey database and choose Create - Agent. The Agent Properties box appears.
2. Give the agent the name ″Send Thank-You″ and select ″Shared Agent.″
3. Select ″On event″ as the trigger.
4. Select the runtime option ″After new mail has arrived.″
5. Close the Agent Properties box.
6. In the Object list, make sure Action is selected.
7. Select ″Simple actions(s)″ from the drop-down list in the Programmer’s pane and click ″Add Action.″
8. Select ″Reply to Sender″ from the list and then click ″Reply to sender only.″
9. In the box for the body of the text, type:
Thank you for taking the time to respond to our survey. We will distribute the results as soon as
they are ready.
10. Click OK.
11. Close and save the agent.

Example of using an agent that mails action item notices


Consider that every week, you want action items mailed from the Meeting Tracking database to the
people who are assigned to each task.
1. Select the Meeting Tracking database, and choose Create - Agent. The Agent Properties box appears.
2. Give the agent the name ″Mail Action Items″ and then select ″Shared Agent.″
3. Select ″On schedule″ as the trigger.
4. Select ″Weekly″ from the list.
5. Click the Schedule button.
6. Select ″Wednesday″ from the ″On day″ list and type the following in select 05:00 PM from the ″At
time″ list.
7. Click OK.
8. In the Target list, select ″All new & modified documents.″

346 Application Development with Domino Designer 7


9. Close the Agent Properties box.
10. Highlight ″Document Selection″ in the Objects list and click the ″Add Condition″ button.
11. In the Condition list, select ″By form″ and select ″Action Item.″ Click Add.
12. Click ″Add Condition″ again.
13. In the Condition list, select ″By field.″ Select Status, contains, Open. Click Add.
14. In the Object list, highlight Action and click ″Add Action.″
15. Select ″Send Mail Message″ from the Action list and click More.
16. In the To box, click Formula and enter the formula:
AssignedTo
17. In the Subject box, click Formula, type the following formula and click OK:
ActionItem + ", due " + @Text(DueDate)
18. In the Body box, type:
This action item has been assigned to you.
19. Click OK.
20. Check ″Include copy of document″ and click OK.
21. Close and save the agent.

Example of using an agent that sends announcements


Consider that you are designing a Corporate Announcements database to which managers want to send
notices for important announcements. To circulate particular announcements, managers select them from
the view and then select the agent that sends notices.
1. To prevent non-managers from running this agent, deselect ″Create private agents″ in the database
access control list for all users except those with Manager access.
2. Select the Corporate Announcements database and choose Create - Agent.
3. Give the agent the name ″Mail announcements″ and select Shared.
4. Select ″On event″ as the trigger.
5. Select ″Agent list selection″ from the list.
6. Select ″All selected documents″ as the Target.
7. Close the Agent Properties box.
8. Highlight Action in the Object list and click ″Add Action.″
9. From the Action list, select ″Send Newsletter Summary.″
10. In the To box, type:
All Personnel
(″All Personnel″ is a group in the Domino Directory.)
11. In the Subject box, type:
Important Announcements
12. In the Body box, type:
Please note the following new announcements:
13. Check ″Include summary for each document in view″ and click OK.
14. Close and save the agent.

Chapter 17. Creating a workflow application 347


348 Application Development with Domino Designer 7
Chapter 18. Enabling an application for Domino Off-Line
Services
Domino Off-Line Services (DOLS) provides a way for users to take IBM Lotus Domino 7 Web
applications offline, work in them, and synchronize the changes with an online replica on the Domino
server. Users are not required to have IBM Lotus Notes 7 client because the applications are accessed
with a browser.

Nearly all Notes functionality is retained when a DOLS-enabled application (called a subscription) is
taken offline. Users can compose, edit, delete, sort, and categorize Notes documents, and perform full-text
searches. DOLS subscriptions can make full use of Java applets, agent execution, and workflow. DOLS
also supports full data replication, retains application logic, and supports the full Notes security model.

The developer and administrator must set up and configure a DOLS subscription for offline use.

The developer copies a number of elements into the subscription, makes design changes if necessary, and
configures the subscription in the Offline Subscription Configuration Profile document.

The administrator makes sure DOLS is installed properly on the server, sets security for the subscription,
sets up agents, makes changes to the Offline Subscription Configuration Profile document if necessary,
and helps users install the subscription.

Once the subscription is enabled, users can access it on the server using a browser. The user clicks ″Go
Offline″ or ″Install Subscription″ from the Online menu on the subscription’s main page and the
subscription is installed on their computer.

Also installed on their computer is the Lotus Domino Sync Manager (previously the iNotes(TM) Sync
Manager), a utility for managing DOLS subscriptions. Users can open subscriptions online or offline,
synchronize, and set subscription properties with the Sync Manager.

For more information, see the following:


v Lotus Domino Sync Manager Help (available from the Help menu of the Lotus Domino Sync Manager)
v Lotus Domino Administrator 7 Help

Overview of DOLS developer tasks


Developers and administrators perform different tasks to enable a subscription for offline use. Developers
perform the following tasks:
1. Copy design elements from the DOLRES.NTF file into the subscription’s main database.
2. (Optional) Customize how users install the subscription.
3. Edit the Offline Subscription Configuration Profile document.
4. Customize the subscription.
5. Tell the administrator they have completed their tasks. Developers who perform administrator tasks
should read the DOLS topics in Lotus Domino Administrator 7 Help.

Copying DOLS design elements into the main database


You must copy several elements from DOLRES.NTF into the main database of your subscription. The
database you choose should be the first database the user sees when opening the subscription. To copy
the elements:

349
1. Open the main database of the subscription. Even if the subscription has multiple databases, copy
DOLS design elements only into the main database.
2. Open DOLRES.NTF (the DOLS Resource template). DOLRES.NTF is in the Domino Data directory.
3. Copy the following pages from DOLRES.NTF into your database:
v DOLS Request Offline ID. This is a hidden page. Do not do anything else to it.
v One of the following:
DOLS Web Control. This page loads ActiveX and/or plug-ins that enable ″Go offline″ and ″Go
Online″ menu items in the database. You must either choose this design element or the ″DOLS
Load Download Page″ as a way for users to download the subscription. For more information on
downloading the subscription, see the topic ″Customizing how users install the DOLS
subscription.″
DOLS Load Download Page. If you prefer to use an icon instead of the DOLS Web Control in your
subscription, use this page. For more information on downloading the subscription, see the topic
″Customizing how users install the DOLS subscription.″
v (Optional) DOLS Web Control Bitmaps. Copy this page if you want to change the default bitmaps
built into the DOLS Web Control. For more information on downloading the subscription, see the
topic ″Customizing how users install the DOLS subscription.″
4. Copy the ″DOLS Offline Configuration″ form from DOLRES.NTF into the Domino subscription. This
form contains the Offline Subscription Configuration Profile form. Every DOLS subscription must
contain this form.
5. Copy the ″Edit Offline Configuration″ agent from DOLRES.NTF into the subscription. This agent
allows you to create an Offline Subscription Configuration Profile document.

Note: Do not copy the agent named ″Delete Configuration Document.″ Deleting an Offline
Subscription Configuration Profile document may cause problems for a subscription. The Delete agent
is included in this template for unusual circumstances only, such as a failed upgrade.
6. Copy the following subforms from DOLRES.NTF into the Domino subscription:
v DOLS Configuration Settings. This is a table of Offline Subscription Configuration Profile document
fields. Do not modify this subform. Because this form inherits its design changes from
DOLRES.NTF, any changes you make may be overwritten.
v DOLS Customize. Use this subform to customize the configuration document. This is the only
subform that you should modify and you can leave it hidden or make it visible. You can create
fields and modify fields dynamically in other subforms. For more information on using the
Customize subform, see the topic ″Customizing fields and design elements in a DOLS
subscription.″.
v DOLS Download Control. This subform contains the JavaScript that loads the Web Control when a
user installs a subscription. This subform only displays in a browser. Do not modify this subform.
Because this form inherits its design changes from DOLRES.NTF, any changes you make may be
overwritten.
v DOLS Download Instructions. This subform contains the default text that the user sees when a
subscription is installed. Do not modify this subform.

Customizing how users install the DOLS subscription


The developer has two choices for how users install and possibly manage the subscription: the Web
Control or an icon. The developer must choose one, then copy the appropriate design element into the
main database of the subscription. They must then create a frame in the main frameset of the
subscription and place either the Web Control or icon in it.

Using the Web Control


The Web Control is the recommended way to have users install a subscription.

350 Application Development with Domino Designer 7


The ″DOLS Web Control″ page (in DOLRES.NTF) loads ActiveX (in Internet Explorer browsers) or
plug-ins (in Mozilla browsers) that enable ″Go offline″ and ″Go Online″ menu items in the subscription.
When users click ″Go Offline″ or ″Go Online″ they can choose several options, including installing the
subscription.

You can cut and paste the contents of the Web Control page to another page or design element, but the
disadvantage of cutting and pasting is that you do not automatically receive changes the next time you
upgrade.

The ″DOLS Web Control Bitmaps″ page (in DOLRES.NTF) contains the default images the user clicks to
open the Web Control menu. You can replace these images with your own by giving your files the same
names as the default files, then deleting and replacing the default files with your own.

Your image files must have the following names to override the default image files:
v DOLCONTROLDEFAULT.BMP - the bitmap that appears when no subscription is installed
v DOLGOOFFLINE.BMP - the bitmap that appears when users open the subscription online once it’s
installed
v DOLGOONLINE.BMP - the bitmap that appears when users open the subscription offline once it’s
installed

One reason you may want to change the default bitmaps is to replace the default English words in the
images with another language. Or, you may want to say something other than ″Install Subscription,″ ″Go
Offline,″ or ″Go Online,″ or use different colors.

You must create a frame for the Web Control in the main frameset of the subscription. The default height
and width for each bitmap file is 64 pixels by 16 pixels. To change the default height and width of the
bitmaps, edit the JavaScript in the ″DOLS Web Control″ page. (Make sure you also adjust the size of the
frame that contains the bitmap.)

Each subscription can have only one Web control.

Using an icon
The ″DOLS Load Download Page″ page contains an icon called DOLS.GIF, which loads into a new frame
in the subscription. Unlike the Web Control, there is no popup menu. A user clicks the icon to install the
subscription. Once the subscription is installed, the user must manage the subscription (for example,
synchronize, or open the subscription online or offline) with the Sync Manager.

An advantage of using this page instead of the Web Control is that the subscription downloads faster. Or
you may want to use your company’s logo as the icon for downloading the subscription. The
recommended way to use this page is to include it as a frame in a frameset. You can also cut and paste
the JavaScript to another page or design element, but the disadvantage of cutting and pasting is that you
do not automatically receive changes the next time you upgrade.

You can replace DOLS.GIF with your own image by opening DOLRES.NTF, choosing Shared Resources -
Images, clicking New Image Resource, and adding your image. Then replace references to DOLS.GIF in
the JavaScript contained in the ″DOLS Load Download Page″ page with the name of your image.

Configuring the DOLS subscription


You choose configuration settings for the subscription in the Offline Subscription Configuration Profile
document. You must edit and save a configuration document in every subscription even if you make no
changes to the document. A subscription can have only one configuration document, even if the
subscription has multiple databases. The configuration document must be stored in the main database.
The main database is the database in the subscription from which the user downloads the subscription.

Chapter 18. Enabling an application for Domino Off-Line Services 351


You can change configuration settings even after users have downloaded the subscription.

To edit the configuration document


1. Copy the appropriate design elements into the main database.
2. Open the database in Notes.
3. Choose Actions - Edit Offline Configuration to open the document. Note that some of the fields have
default values, which you can change. You can use wild card characters in any field.
4. Click the Basics tab. The name of the main database should be in the ″Subscription title″ field. If it is
not, enter it.
5. Click the Services tab and fill in the following fields.

Name of Field Action


Domino services to install offline The offline subscription may need support for full-text indexing,
v Basic services (required) LotusScript and unscheduled agents (such as Web open), Java
back-end classes and applets, MAPI enablement, or custom services.
v Full-Text Indexing
v LotusScript and unscheduled agents Select the appropriate boxes so that only files the users actually need
v Java classes and applets are downloaded to their machine.
v Custom Services MAPI enablement is available only when you use the Extended Mail
v MAPI enablement Template (MAIL6EX.NTF) for Web mail.
v Default Language
Choose a default language for the Web Control menu and the Domino
Sync Manager. Users can override this setting by selecting a different
language from the Web Control menu.
Custom services to install offline This field is available only when you select the ″Custom services″ box.

Enter the name of custom service files to be unpacked and executed on


the user’s computer during installation of the subscription. Custom
services have the following syntax: CustomServiceName [Setup.exe
[SetupArguments]]. For example:

mycustomname mysetupfile.exe -z -r -u

If you specify more than custom service, separate the services with
commas. For example:

mycustomname mysetupfile.exe -z -r -u, mycustomname2


mysetupfile2.exe -z -r -u

For more information on custom file sets, see the topic ″Creating
custom file sets for a DOLS subscription.″

6. Click the Schedule tab and complete the following fields. Note that the user can override most of
these fields from within the Subscription Properties box of the Domino Sync Manager.

Name of Field Action


Type of schedule
Daily Select this field, then specify the time of day you want synchronization
to occur.
Weekly Select this field, then check the days you want the synchronization to
occur.
Monthly Select this field, then specify the day of the month you want the
synchronization to occur.
Start time Enter the time of day for the subscription to start scheduled
synchronization.

352 Application Development with Domino Designer 7


Name of Field Action
Frequency
Repeating schedule Select this box if you want synchronization to repeat at certain
intervals after the initial start time.
Interval Specify the time between repeating synchronizations. Enter a number
and then choose either minutes or hours. For example, you can enter
180 minutes or 3 hours.
Limitations
Stop synchronization at Specify the time you want the synchronization to stop.
Recurrence exceptions
Schedule disabled Select this box to make a disabled synchronization schedule the default
state. The subscription only synchronizes once, when it is installed.
The user can override this setting in the offline synchronization
properties.

7. Click the Sync Options tab and complete the following fields:

Name of Field Description


File Rules
Required files to replicate Enter the subscription’s required files. Required files are databases,
templates or directories that are automatically installed offline, and are
replicated every time the subscription is synchronized.

All required files and directories must be specified relative to the


server’s data directory.

For tips on using directory names and wildcards when you specify
more than one Required file or Optional file, see the topic ″Creating
multiple database DOLS subscriptions.″
Optional files to replicate Enter the subscription’s optional files. Optional files are databases,
templates or directories that can be enabled or disabled in the sync
manager for offline installation and replication. For example, in
addition to the required file(s), you may want to download a related
Help database or an archived discussion database as an optional file.

All optional files and directories must be specified relative to the


server’s data directory.

Optional databases replicate as ″stubs,″ meaning only the design is


replicated. Users can open Sync Properties, click the Sync Options tab,
select the database, and deselect the disable box. The data is then
replicated at the next synchronization. To save disk space, users can
disable an optional file, and the data is removed at next
synchronization.

Enable replication of optional files by default:

Select this box to automatically download and synchronize new


databases found in the subscription’s directories on the server. For
example, if one of the optional databases is designed to create new
databases, the new databases are automatically downloaded and
synchronized.

Chapter 18. Enabling an application for Domino Off-Line Services 353


Name of Field Description
Directory catalog Synchronize directory catalog:

Select this box to install a directory catalog with the subscription. Then
enter the file name, including directory path, of the catalog database
on the server (for example, dircats\mydircat.nsf). If the server
administrator has specified a default offline directory catalog for the
server by adding $DOLSDirectoryCatalog = nameofcatalog.nsf to the
NOTES.INI on the server, you can leave this field blank and the
server’s default offline catalog is replicated with the subscription. A
catalog filename specified here will override the server’s default offline
directory catalog.

Choose the ″Replicate as an optional file″ checkbox to specify the


catalog as an optional file. If the directory catalog is specified an
optional file, the ″Enable replication of optional files by default″
checkbox must be checked for the catalog to replicate the first time.

In order for Domino Web Access for Web Mail users, to take a
directory catalog offline, you must add the name of a directory catalog,
including the NSF extension, to the $DOLSDirectoryCatalog setting in
the server’s NOTES.INI file.

For more information on using directory catalogs with DOLS, see the
topic ″Adding a directory catalog to the application″ before adding one
to your subscription.
Encryption Encrypt this subscription:

Select the box to enable encryption. Then select the level of encryption.
Encryption prevents an unauthorized user from accessing the offline
subscription’s data using another software product.
v If the subscription has multiple databases, all of these databases are
encrypted.
v If the subscription has a shared file, you must encrypt all
susbcriptions sharing the file. An unencrypted subscription may not
be able to open an encrypted file.
v Using strong encryption causes a database to open more slowly than
it would using a weaker encryption or no encryption.
Note: Do not encrypt the database from the Database Properties box.
Use the Offline Subscription Configuration document to prevent
unauthorized users from reading subscription data using other
applications.

Syc Options
Date Filtering Only sync documents modified within the last [number] days:

Select this box to preset a default, date-based filter on all databases


created offline. For example, if you specify 30 days, only documents
created or modified in the last 30 days will synchronize. Once
installed, users can reset this for each subscription file using the
Domino Sync Manager.

354 Application Development with Domino Designer 7


Syc Options
Halt Conditions v Limit database size to [number] MB: Select this box to specify the
maximum size in megabytes of the offline database. You cannot
specify a number less than 10.
v Limit subscription size to [number] MB: Select this box to specify the
maximum size in megabytes of the entire offline subscription. You
cannot specify a number less than 10.

You can preset an automatic halt to the offline synchronization when a


database exceeds a particular size, or when the subscription as a whole
exceeds a particular size. The user can override this setting.
Note: Be careful not to specify a size that may be too limiting. The
offline subscription may not be fully operational if synchronization is
interrupted prematurely.
Sync Options: Optional actions
Full-Text Index subscription after sync Select this box to force full-text indexing of the subscription after
synchronization. The user can override this setting.
Compact subscription after sync Select this box to force the subscription to compact after
synchronization.
Notify on completion of sync Select this box if you want the user to receive a message when
synchronization is complete. The user can override this setting.

If warnings are displayed during the synchronization process, and this


option is selected, each warning message will display.
Route mail on client shutdown Select this box so that pending outgoing mail messages are sent before
the user exits from the Domino Sync Manager. The user can override
this setting.
Replicate on client shutdown Select this box so that synchronization occurs before the user exits
from the Domino Sync Manager. The user can override this setting.
Use multi-user data directory Select this box so that the subscription can be installed to a client with
a Notes multi-user setup. Subscription data is stored in the user’s
personal profile data directory.
Allow per-user shared subscription data Select this box to allow the subscription to share a file with another
subscription, as long as as the same user has installed both files.

For example, a user installs this subscription with the directory catalog
dircat1.nsf. If the user then installs another subscription that uses
dircat1.nsf., and also selects this option, the two subscriptions share
dircat1.nsf.

All subscriptions that share the same file must be either encrypted or
not encrypted. Non-encrypted subscriptions may not be able to share a
file that is encrypted.

Chapter 18. Enabling an application for Domino Off-Line Services 355


8. Click the Admin tab and complete the following fields:

Name of field Action


Push subscription settings: Push subscription settings to Domino Sync Manager.

Select this box to push changes made to the active Off-Line Subscription
Configuration Profile Document (on the server), down to the Domino
Sync Manager (on the client), without requiring a reinstallation of the
subscription.

The following are the only settings and actions that cannot be changed
on the user’s computer unless the user deletes and reinstalls the
subscription.

Encryption

Per-user shared subscriptions

Multi-user data directories

Passthru server settings

Optional TCP/IP addresses

A change in the subscription title

Adding new services or custom filesets

Deleting or moving the main.nsf

Force user to accept subscription changes. This box is only visible when
″Push subscription settings to Domino Sync Manager″ is selected. Select
this box to force the user to accept changes in the Offline Subscription
Configuration Profile document. Not selecting this box allows users to
prevent the changes from occurring on their subscriptions.
Read only subscription settings: Make schedule read-only. Select this box to dim the scheduled
replication settings in the Properties dialog - Schedule tab of the
subscription on the user’s computer. You can push this to users by
selecting it before they install the subscription, or by using the ″Push
subscription settings″ feature.

Make sync options read-only. Select this box to dim the Sync Options
settings in the Properties dialog - Sync Options tab of the subscription
on the user’s computer. You can push this to users by selecting it before
they install the subscription, or by using the ″Push subscription
settings″ feature.
Passthru server settings: Use passthru server to connect to destination server. Select this box to
use a passthru server to connect to the Domino server that hosts the
subscription. You must enter the name of the passthru server.

356 Application Development with Domino Designer 7


Name of field Action
Network Settings: Use optional TCP/IP address to connect to destination server. Select this
box to provide primary and/or secondary TCPIP addresses for the
destination Domino server hosting the subscription. This is especially
useful for users who access the server through both an intranet and an
extranet. If the primary address is not reachable, the Domino Sync
Manager tries the secondary address to connect to the server.

Then enter the name of the primary and secondary addresses. If users
connect to the host server through a passthru server, the addresses must
be for the passthru server.

Alternatively, an administrator can configure these settings for all the


subscriptions hosted on a particular server by adding addresses to the
$DOLS_TCPIPAddress and $DOLS_TCPIPAddress2 settings in the
server’s NOTES.INI.
Security Settings: Enable this setting so that the user’s offline Internet password remains
synchronized with their online Internet password. This setting works
only when the Online Configuration document Security Settings field
″Keep Internet Password Synchronized″ is enabled.

9. (Optional) At the bottom of the configuration document, select whether to display the default
download page or create your own download page. The download page is what users see while
they’re installing a subscription. It’s useful for showing instructions, company graphics, warnings, or
tips. Do one of the following:
v Leave ″Display default download page contents″ selected to have the download page contain the
default text and graphics. You can add text, HTML, or images in the rich-text field below the
default text and graphics.
v Select ″Display only the custom contents below″ to create a download page. A rich-text field
appears in which you can add text, HTML, or images.
10. Save and close the configuration document.
11. Save and close the subscription.
12. (Optional) Customize the subscription. For more information on customizing the subscription, see
the topic ″Optional tasks for DOLS developers.″

Creating multiple database DOLS subscriptions


A subscription can contain several databases. Although some databases can be optional, others -- like the
main database (the one containing the DOLS design elements) -- are required.
v Required databases are those databases necessary for the subscription to work offline. Required
databases replicate in full, meaning both the design and data are sent to the user’s machine.
v Optional databases replicate as ″stubs,″ meaning only the design is replicated. When you include
optional databases in a subscription, you enable users to download the data in the required databases
more quickly. Users can then download the optional data later.

Here are a few tips to keep in mind when enabling a multiple database subscription for offline use:
v Identify all the databases in your subscription.
v Identify the main database and copy the DOLS design elements only to the main database. Do not
copy the design elements to each database in the subscription.
v Use relative URLs and relative paths to link between databases. Avoid absolute URLs and paths, which
do not work offline.
For example, use /dev/mynsf.nsf as opposed to http://www.servername.com/dev/mynsf.nsf.

Chapter 18. Enabling an application for Domino Off-Line Services 357


v Use wildcards (*) or use a directory when entering values in either the ″Required files to replicate″ or
″Optional files to replicate″ fields on the Rules tab of the Offline Subscription Configuration Profile
document.
If you enter explicit file names in either of these fields, you must re-edit the configuration document
each time you add or delete files. For example, if the field contains three files -- SalesApp\main.nsf,
SalesApp\contacts.nsf, SalesApp\custom.ntf -- you must update the field each time a file is added to
the SalesApp\ directory or else that file will not replicate offline to join the rest of the subscription.
By using wildcards (*) in either of these fields, you specify that all database files or all template files in
a given directory are automatically replicated, even files recently added. For example, if you use a
wildcard in this way, all NSF files in the SalesApp directory are replicated:
SalesApp\*.nsf
Similarly, to make sure all NTF files in the SalesApp directory are included in the replication, specify
the following:
SalesApp\*.ntf
By using just the directory, without a wild card, in either of these fields, you specify that all files in the
directory, whether NSF or NTF, are replicated, even files recently added, as in this example:
SalesApp

Optional tasks for DOLS developers


This section includes additional information and optional tasks for the DOLS developer:

Creating custom file sets for a DOLS subscription

Customizing fields and design elements in a DOLS subscription

Creating multiple database DOLS subscriptions

Adding a directory catalog to a DOLS subscription

Adding time zones to a DOLS subscription

Setting a sort order for a DOLS subscription

Creating custom file sets for a DOLS subscription


You can have custom programs run on the subscription after it is installed to the user’s machine. You
must use a DOLS utility called DOLMKINF to have your custom program install offline. Do the
following to have your program install and run offline.
1. Create a self-extracting executable (EXE) file containing your program files.

Note: For Windows client platforms, the file name must begin with ″N_ ″ to signify that it is a Win32
file. For example: N_MYCUSTOM.EXE.
2. Copy the file to the following directory on the Domino server:
Lotus\Domino\Data\domino\html\download\filesets
3. In the command prompt, navigate to the \filesets directory and run the DOLMKINF utility
(DOLMKINF.EXE) by entering arguments with the following syntax:
DOLMKINF -d path [-f filename] [-v version] [-h]

Argument Description
-d Enter this argument, then enter the directory path to your program files (all the separate files, not
the .EXE or .DLL.)

358 Application Development with Domino Designer 7


Argument Description
-f Enter this argument, then enter a name for the INF file, including the INF suffix. If you do not use
the -f argument, the default file name will be the same as the name of the directory specified in
the -d argument.

The INF name must match the compressed EXE or .DLL file name. For example, if the EXE file is
N_MYCUSTOM.EXE, specify N_MYCUSTOM here to produce N_MYCUSTOM.INF.
-v Enter this argument, then specify a version number. If you do not use this argument, the default
version number is 0.0. This version number is compared against any existing custom programs
previously downloaded.

The new program is not downloaded if a program with a higher version number exists on the
user’s machine.
-h Enter this argument to output help.
Examples DOLMKINF -d project\myfiles

DOLMKINF -d project\myfiles -f project\n_mycustom

DOLMKINF -d project\myfiles -f project\n_mycustom -v 1.0

The utility generates an INF file containing the number of files in the program; the number of bytes
for the files in the program; and the version number of the program.
4. Open the Offline Subscription Configuration Profile document. Click the Services tab, then select
″Custom Services.″
5. Specify your program name (without the N_ prefix or .EXE suffix) in the ″Custom Services to install
offline″ field. For example: MYCUSTOM
In this example, DOLS looks for N_MYCUSTOM.EXE and N_MYCUSTOM.INF in the \filesets
directory. The files are installed to the Domino Web Access client program directory on the user’s
machine.
6. (Optional) Specify a setup program and any arguments your program takes. For example:
MYCUSTOM SETUP.EXE -r
In this example, DOLS looks for N_MYCUSTOM.EXE and N_MYCUSTOM.INF in the \filesets
directory. The files are installed to the Domino Web Access client program directory on the user’s
machine.
Then SETUP.EXE runs and takes the -r argument.

Note: If you specify more than one program, separate the entries with commas.

Customizing fields and design elements in a DOLS subscription


The DOLS Customize subform provides a way to override default values in the fields of other subforms
in the subscription. This gives you the flexibility to customize the subscription to your organization’s
needs. The values that you can override are listed in the following table. You can also attach identity
icons to this subform.

After you have copied the DOLS Customize subform from DOLRES.NTF into the subscription, you can
edit it in IBM Lotus Domino Designer 7. Because this subform loads after all other subforms, you can use
events such as PostOpen to override the default values for other fields. You can also place into this
subform field validation formulas that override other fields. During download, the DOLS Customize
subform is loaded by a DSAPI filter on the server and all validation formulas are retriggered to bring in
any new information. For example, the @today formula brings in today’s date.

Chapter 18. Enabling an application for Domino Off-Line Services 359


Identity icons
You can attach identity icon files to the DOLS Customize subform that identify the subscription on the
user’s computer. You can attach from one to three identity icons to this subform by choosing File - Attach
in Lotus Domino Designer 7. The icons you attach must be named:
v subscription.ico - This icon appears on the user’s Windows desktop and serves as a shortcut to the
offline subscription. The default is

v syncstate1.ico - This icon and syncstate2.ico toggle on the task bar during synchronizations of the
subscription. The default is

v syncstate2.ico - This icon and syncstate1.ico toggle on the task bar during synchronization of the
subscription. The default is

Note that each ICO file has a size limit of 15KB.

Published design elements


The following design elements are published, meaning they are available for customization. You can
manipulate these values with LotusScript or Formula language statements placed in the DOLS Customize
subform. Design elements not named in this table are subject to change with future releases. You should
not reference them programmatically.

Note: Notes C or C++ API access to the following design elements is not supported. The Notes editor
must still execute some formulas in other subforms through the Offline Subscription Configuration Profile
document.

Element
Name Type Where Found Comments
DOLSLoadDownloadPage Page DOLRES.NTF The published program name for
most design elements is not the
DOLSRequestOfflineID name with spaces in it - shown, for
example, in the views in Domino
DOLSWebControl Designer. The name with spaces
may change over time or locale.
DOLSWebControlBitmaps Page DOLRES.NTF The page that contains the DOLS
Web Control bitmaps that override
the default bitmaps.
dolcontroldefault.bmp Bitmap file DOLSWebControlBitmaps The bitmap that appears when no
attachment Page subscription is installed.
dolgooffline.bmp Bitmap file DOLSWebControlBitmaps The bitmap that allows you to open
attachment Page a subscription offline when you are
online with the subscription.
dolgoonline.bmp Bitmap file DOLSWebControlBitmaps The bitmap that allows you to open
attachment Page a subscription online when you are
offline with the subscription.
DOLSEditOfflineConfiguration Agent DOLRES.NTF
DOLSOfflineConfiguration Form DOLRES.NTF
DOLSConfigurationSettings Subform DOLRES.NTF

360 Application Development with Domino Designer 7


Element
Name Type Where Found Comments
DOLSCustomize Subform DOLRES.NTF
DOLSDownloadControl Subform DOLRES.NTF
DOLSDownloadInstructions Subform DOLRES.NTF
SubscriptionTitle Field DOLSConfigurationSettings Title of subscription.
Subform
subscription.ico Icon file DOLSCustomize Subform Default subscription icon. Appears
attachment on user’s desktop.
syncstate1.ico Icon file DOLSCustomize Subform One of two animation icons for
attachment active sync of this subscription.
Appears on user’s task bar.
syncstate2.ico Icon file DOLSCustomize Subform One of two animation icons for
attachment active sync of this subscription.
Appears on user’s task bar.
ChooseDownloadText Field DOLSConfigurationSettings Download text radio button
Subform
Basic Field DOLSConfigurationSettings Basic services check box
Subform
Search Field DOLSConfigurationSettings Full-text indexing check box
Subform
LotusScript Field DOLSConfigurationSettings LotusScript and agents check box
Subform
JavaApplets Field DOLSConfigurationSettings Java classes and applets check box
Subform
CustomFile Field DOLSConfigurationSettings Custom services check box
Subform
CustomFileNames Field DOLSConfigurationSettings Custom services list
Subform
CanonicalServerName Field DOLSConfigurationSettings Hidden field that must always
Subform have canonical name of current
server.
ScheduleType Field DOLSConfigurationSettings Schedule type radio button
Subform
Weekdays Field DOLSConfigurationSettings Check box selection of multiple
Subform weekdays.
Monthdays Field DOLSConfigurationSettings Numeric - not less than 1 or greater
Subform than 31
RunOnce Field DOLSConfigurationSettings Check box
Subform
StartTime Field DOLSConfigurationSettings Date/time
Subform
Repeat Field DOLSConfigurationSettings Check box
Subform
RepeatInterval Field DOLSConfigurationSettings Positive numeric interval
Subform
RepeatIntervalUnit Field DOLSConfigurationSettings Selection list
Subform

Chapter 18. Enabling an application for Domino Off-Line Services 361


Element
Name Type Where Found Comments
StopSync Field DOLSConfigurationSettings Check box
Subform
SyncStopTime Field DOLSConfigurationSettings Datetime
Subform
LimitSyncDuration Field DOLSConfigurationSettings Check box
Subform
SyncDuration Field DOLSConfigurationSettings Positive numeric interval (minutes)
Subform
Disabled Field DOLSConfigurationSettings Check box
Subform
RequiredFilesToReplicate Field DOLSConfigurationSettings Text list
Subform
AutoReplicate Field DOLSConfigurationSettings Check box
Subform
OptionalFilesToReplicate Field DOLSConfigurationSettings Text list
Subform
LimitReplicateDaysBack Field DOLSConfigurationSettings Check box
Subform
ReplicateDaysBack Field DOLSConfigurationSettings Positive numeric integer
Subform
LimitDBSize Field DOLSConfigurationSettings Check box
Subform
DBSizeLimit Field DOLSConfigurationSettings Positive numeric integer
Subform
LimitSubscriptionSize Field DOLSConfigurationSettings Check box
Subform
SubscriptionSizeLimit Field DOLSConfigurationSettings Positive numeric integer
Subform
NotifyOnCompletion Field DOLSConfigurationSettings Check box
Subform
RouteMailOnShutDown Field DOLSConfigurationSettings Check box
Subform
RunReplicationOnShutdown Field DOLSConfigurationSettings Check box
Subform
CustomDownloadText Field DOLSDownloadInstructions Rich text for download page
Subform

Adding a directory catalog to a DOLS subscription


Adding a directory catalog to a DOLS subscription allows users to take Domino Directory information
offline. When you add this NOTES.INI setting, the option ″Include server’s Domino Directory″ is
available in the Domino Web Access Offline preferences. Users need to enable this option to allow
address look ups, which is necessary to encrypt mail offline. To add a directory catalog to a subscription:
1. Read the following.
v Adding a catalog means more for a user to download. To keep download time reasonable, you may
want to create a directory catalog specifically for offline users, which contains only the information
they absolutely need.

362 Application Development with Domino Designer 7


v To add a default catalog, open the NOTES.INI file on the server and add the line
$DOLSDirectoryCatalog=nameofcatalog.nsf (nameofcatalog being the actual name of the catalog).
Once you do this, you don’t need to specify a catalog in the ″Directory catalog to replicate″ field in
the Offline Configuration Profile document.
v From the DOLS Customize subform, you can create a field that looks up a catalog’s name on the
server record and populates the ″Directory catalog to replicate″ field with that name.
2. Open the Offline Subscription Configuration Profile document.
3. Enter the name of the catalog in the ″Directory Catalog″ field in the Rules tab.
4. Restart the server.

Adding time zones to a DOLS subscription


When there is a date and time displayed in the subscription, add a time zone field, too. If you do not
specify the time zone, you may confuse the offline user because the subscription uses the clock of the
local machine (not the clock of the server) when it runs locally. For example, a Chicago user might view
an offline document that displays the local time as 10 AM. At the same time, the online version of the
same document displays the time as 11 AM. By adding time zones, you can display the times as 10 CST
and 11 EST.

Setting a sort order for a DOLS subscription


A sort order language determines the rules by which documents are ordered in views. For example, some
applications use a sort order in which documents are sorted by number first, then letter.

The default sort order of an application is determined by the operating system of the computer it’s on.
This could be a problem with a DOLS subscription if the sort order offline (on the user’s computer) is
different from the sort order online (on the Lotus Domino 7 server). Users would see the same
information in the views, but in a different order than you intended.

To ensure that the same sort order is used online and offline, specify a sort order in the Database
Properties - Design tab of each database in the subscription. Select ″Multilingual database″ and select a
sort order language.

Chapter 18. Enabling an application for Domino Off-Line Services 363


364 Application Development with Domino Designer 7
Chapter 19. Security in an application
Domino offers a multi-layered approach to security. Server administrators can secure databases, servers,
and domains. Database designers and managers control the following:
v Application Security
Use the database access control list (ACL) to restrict access that specific users and servers have to an
application. You can also use the Advanced section of the ACL to further restrict application access for
Web users.
v Design element security
Use the database access control list in conjunction with access control fields to restrict access that
specific users and servers have to an application. You can also use access lists and special fields to
restrict access to specific design elements within an application.
v Encryption and database signing
You can further ensure data privacy by encrypting a database with an ID so unauthorized users cannot
access a locally stored copy of the database. You can also sign or encrypt mail messages users send and
receive, and you can sign the database or template to protect design elements from manipulation from
outside formulas.

The database access control list


Every database has an access control list (ACL) that specifies the level of access that users and servers
have to a database. Although the names of access levels are the same for users and servers, those
assigned to users determine the tasks that users can perform in a database, while those assigned to
servers determine what information within the database the servers can replicate.

You must have Manager access to create or modify an ACL. Then, for each user name, server name, or
group name in an ACL, you can specify:
v An access level
v Access level privileges
v A user type
v Roles

Note: You can further restrict access to specific documents and fields within those databases using the
Extended ACL, which is used in the Domino Directory, the Extended Directory Catalog, and the
Administration Requests database. Work with your server administrator to apply these security measures.

For more information on server access levels and replication, see Administering the Domino System.

Setting up a database ACL


Plan the database access for the application before you add users, groups, or servers to a database ACL.
After you set up a database ACL, users can click the Effective Access button on the ACL dialog box in
the Notes client to view their level of access to a database.

Note: You can make changes to multiple ACLs on a server through the Multi-ACL Management dialog
box in the Administrator Client. You can also edit an ACL for a single database using the File - Database
- ACL dialog box in the Notes client.

365
To set up a database ACL
1. Make sure that you have:
v Manager access in the database ACL
v Created the roles and groups that you want to use in the ACL
2. Select the database icon from your Bookmark pane.
3. Choose File - Database - Access Control.
4. Add entries for Notes users, servers, groups, and authenticated Internet users.
5. Set the access level for each entry.
For information on assigning anonymous access for Web users, see Administering the Domino System.
6. (Optional) For additional security, select a user type for the each entry.
7. (Optional) Refine the entries by restricting or allowing additional access level privileges.
8. (Optional) Assign roles to ACL entries. The role displays a check mark when selected. If no role
exists in the database, the role option is not displayed.
9. (Optional) Enforce a consistent ACL across all replicas of the database.
10. (Optional) Click Advanced and accept or change the Web access level in the ″Maximum Internet
name & password access″ list.
11. Click OK to save your changes.

Access levels in the ACL


Access levels assigned to users in a database ACL control which tasks users can perform in the database.
Access level privileges enhance or restrict the access level assigned to each name in the ACL. For each
user, group, or server listed in the ACL, you select the basic access level and user type. To further refine
the access, you select a series of access privileges.

Note: If you are designing a template (an .NTF file) for others to use to create applications, make sure
the default access is at least Reader so that users and/or servers can successfully read from the template
when creating or refreshing .NSF files based on that template.

Access levels assigned to servers in a database ACL control what information within a database the
servers can replicate.

To access a database on a particular server, a Notes user must have both the appropriate database access
specified in the ACL as well as the appropriate access specified in the Server document in the Domino
Directory.

For more information on server access levels, see Administering the Domino System.

For more information on database access for Internet users, see ″Maximum Internet name-and-password
access″ later in this chapter.

CAUTION:
Administrators who are listed in the Full Access Administrators, Administrators, and Database
Administrators fields in the Server document are allowed to delete any database on the server, even if
they are not listed as managers in the database ACL.

366 Application Development with Domino Designer 7


This table shows the user access levels, listed from highest to lowest.

Access level Allows users to Assign to


Manager Modify the database ACL. Two people who are responsible for the
database.
Encrypt the database.

Modify replication settings.

Delete the database.

Perform all tasks allowed by lower access levels.


Designer Modify all database design elements. A database designer and/or the person
responsible for design updates.
Create a full-text search index.

Perform all tasks allowed by lower access levels.


Editor Create documents. Any user allowed to create and edit
documents in a database.
Edit all documents, including those created by
others.

Read all documents unless there is a Readers


field in the form. If there is a Readers field, the
Editor must be listed to be able to read or edit
the document.
Author Create documents if the user or server also has Users who contribute documents to a
the Create documents access level privilege. database.
When you assign Author access to a user or
server, you must also specify the Create
documents access level privilege.

Edit the documents where there is an Authors


field in the document and the user is specified
in the Authors field.

Read all documents unless there is a Readers


field in the form. If there is a Readers field, the
Author must be listed to be able to read
documents.
Reader Read documents where there is a Readers field Users who only need to read documents in
in the form and the user name is specified in the a database but not create or edit documents.
field.
Depositor Create documents. Users who contribute documents but who
do not need to read or edit their own or
other users’ documents. For example, use
Depositor access for a ballot box
application.
No Access Have no access, with the exception of options to Terminated users, users who do not need
″Read public documents″ and ″Write public access to the database, or users who have
documents.″ These are privileges that designers access on a special basis.
may choose to grant. Note: You may want to specifically assign
No Access to individuals who should not
have access to a database, but who may be
members of a group that does.

Chapter 19. Security in an application 367


To view ACL entries by access level
You can view ACL entries by access level to see which users, server, or groups are assigned to a specific
access level.
1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmarks pane.
3. Choose File - Database - Access Control.
4. Click the arrow next to ″People, Servers, Groups″ and select an access level. The ACL displays only
those names with the selected access level.
5. Click OK.

Access level privileges in the ACL


You can expand or restrict the access level for each user, group, and server by adding optional privileges
or removing default privileges within an access level.

This table lists the user access level privileges from highest to lowest.

Access level Default privileges Optional privileges


Manager Create documents Delete documents

Create private agents Replicate or copy documents

Create personal folders/views

Create shared folders/views

Create LotusScript/Java agents

Read public documents

Write public documents


Designer Create documents Delete documents

Create private agents Create LotusScript/Java agents

Create personal folders/views Replicate or copy documents

Create shared folders/views

Read public documents

Write public documents


Editor Create documents Delete documents

Read public documents Create private agents

Write public document Create personal folders/views

Create shared folders/views

Create LotusScript/Java agents

Replicate or copy documents

368 Application Development with Domino Designer 7


Access level Default privileges Optional privileges
Author Read public documents Create documents

Delete documents

Create private agents

Create personal folders/views

Create LotusScript/Java agents

Write public documents

Replicate or copy documents


Reader Read public documents Create private agents

Create personal folders/views

Create LotusScript/Java agents

Write public documents

Replicate or copy documents


Depositor Create documents Read public documents

Write public documents

Replicate or copy documents (only if


″Read public documents″ has been
granted)
No Access None Read public documents

Write public documents

Replicate or copy documents (only if


″Read public documents″ has been
granted)

Create documents
Select this privilege for all users with Author access. If you deselect this privilege to prevent Authors
from adding any more documents, they can continue to read and edit documents they’ve already created.

Delete documents
Authors can delete only documents they create. If this privilege is deselected, a user can’t delete
documents, no matter what the access level. If a form contains an Authors field, Authors can delete
documents only if their name, a group that contains their name, or a role that contains their name
appears in the Authors field.

Create private agents


A user can run private agents that perform tasks allowed by the user’s assigned access level in the ACL.
Since private agents on server databases take up disk space and processing time on the server, you may
want to deselect this privilege if performance is a concern.

A server administrator can further restrict a user’s right to run agents in the Agent Restrictions section of
the Server document in the Domino Directory. Therefore, even if you grant a user the ″Create
LotusScript®/Java agents″ access level in a database ACL, the Server document controls whether or not
the user can run an agent on a particular server.

Chapter 19. Security in an application 369


Create personal folders/views
Personal folders and views created on a server are more secure than those created locally, and they can
be made available on multiple servers. Also, administrative agents can operate only on folders and views
stored on a server. If server space is a concern, deselect the ″Create personal folders/views″ option. Users
will still be able to create personal folders and views on their local workstation.

Create shared folders/views


Deselect this privilege to maintain tighter control over database design and to prevent users from creating
folders and views that are visible to others. A user assigned this privilege can create folders and views
that are visible to others.

Note: Users who have this privilege can modify or delete any shared folder, view, or navigator in the
database, regardless of whether they created it. Use caution when granting this privilege.

Create LotusScript/Java agents


Since LotusScript and Java agents on server databases can take up significant server processing time, you
may want to restrict which users can run them.

Whether or not a user can run agents depends on the access set by the Domino administrator in the
Agent Restrictions section of the Server document in the Domino Directory. Even if you select ″Create
LotusScript/Java agents″ for a name in the ACL, the Server document still controls whether or not the
user can run the agent on the server. Work with your server administrator to set access rights for users to
run agents on a server.

Read public documents


Select this privilege to allow users who have No Access or Depositor access to read documents and to see
views and folders with the property ″Available to Public Access users.″ A form must contain a text field
named ″$PublicAccess″ with an assigned field value of one. Documents created from that form are public
document.

Write public documents


Select this privilege to allow users to create/edit specific documents that are controlled by forms having
the property ″Available to Public Access users.″

Replicate or copy documents


Select this privilege to allow users to:
v create a new local replica or local copy of a database;
v copy, print, or forward documents in the database, or parts of these documents; and
v select all text in a document opened in read mode.

Note: Deselecting this option is not a true security measure because users can still print using Ctrl+Print
Screen or they can open a document and copy data to the clipboard.

The Notes-generated field $KeepPrivate captures whether the current user has replicate or copy privileges
for the document. This setting applies only to Notes clients.

Roles in the ACL


A database designer can assign special access to database design elements and database functions by
creating roles. A role defines a set of users and/or servers. Roles are similar to groups that you can set up
in the Domino Directory. However, unlike groups, roles are specific to the database in which they are
created.

Once you create a role, you can use it in database design elements or functions to restrict access to those
elements or functions. For example, you may want to allow only a certain group of users to edit certain

370 Application Development with Domino Designer 7


documents in a database. You could create a role named ″DocEditors″. That role would then be added to
the Authors fields of those documents, and assigned to those users who are allowed to edit those
documents.

You must have Manager access to create roles in the database ACL. You must create a role before you
assign it to a name or group in the ACL. Once you have created roles in an ACL , they are listed in the
’Roles’ list box on the Basics panel of the ACL dialog box. Role names appear in brackets -- for example,
[Sales]. When you add an entry to a database ACL, you can assign them to a role by selecting a role from
the Roles list box.

CAUTION:
If you create a role that restricts access to part of an application and you do not assign it to yourself,
you will be restricted from accessing that part of the application in both the Notes client and in
Designer. Make sure you assign each role to yourself as you create it to avoid this problem.

This table describes the design elements to which the database designer can restrict access by using roles.

To restrict who can The designer uses


Edit specific documents An Authors field
Edit specific portions of a document Sections
Read specific documents A Readers field or a Read access list on the Security tab of
the Document Properties dialog box
View and read documents in a specific view View properties
View and read documents in a specific folder Folder properties
Read documents created with a specific form Form properties
Create documents with a specific form Form properties

CAUTION:
Using roles to restrict access to database elements is not a foolproof security measure. For example, if
a designer restricts access to certain documents in a database, the database manager or Domino
administrator must remember that documents inherit their Read access list from the Read access
option that is set in the Form Properties box for the form used to create the document. Therefore,
anyone with Editor access or above in the database ACL can change a document’s Read access list.

To create or edit roles


You must create a role before you can assign it to a name in the ACL.
1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your bookmarks page.
3. Choose File - Database - Access Control.
4. Click Roles.
5. Do one of the following:
v To create a role, click Add, and type a name for the role.
v To rename a role, click Rename. In the Rename Role box, type a new name for the role.
v To delete a role, click Remove, and type the name of the role that you want to delete.
6. Click OK twice.

Notes
v You do not need to include any brackets in the role name when adding or removing a role. However,
when you rename a role, you must type the role name exactly as it appears in the ACL, including the
brackets and case-sensitive characters.

Chapter 19. Security in an application 371


v To display a role assigned to a person, group, or server, select an entry in the ACL. If a check mark
appears next to a role in the Roles box, the selected person, group, or server is assigned to the role.

Editing the database ACL


You can edit, delete, and rename entries in an ACL, as well as change the access assigned to entries.

To edit entries in the ACL


1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmark pane.
3. Select File - Database - Access Control.
4. Select a name.
5. Do one of the following and then click OK:
v Click Remove.
v Click Rename, then type the new name.
v Change the assigned user type, access level, access level privilege, and roles, as necessary.

Tip: To display entries by access level, click the arrow next to ″People, Servers, and Groups,″ and then
select a specific access level.

To add entries to the ACL by access level


1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmarks pane.
3. Select File - Database - Access Control.
4. Click Add.
5. Do one of the following to add a name to the ACL:
v Select the person icon and continue to Step 6.
v Type the name of a user, group, or server and continue to Step 8.
6. Click the arrow and select a Domino Directory or Personal Address Book. Using the name picker in
the dialog box, you can select from the directories and address books available to you to find the
name you seek.
7. Click Add.
8. (Optional) Select a user type from the list in the User Type box.
9. Select an access level from the list in the Access box.
10. (Optional) Refine the access level by selecting or deselecting additional access level privileges, if
available.
11. (Optional) Select a role from the Roles box. The role displays a check mark when selected.
12. Click OK to save your changes.

Default ACL entries


A new database, by default, contains these entries in the ACL:
v -Default-
v Database creator user name
v LocalDomainServers
v OtherDomainServers

All of these entries, except for the database creator’s user name, are group names. The -Default- group is
the only group that is specific to a database and not related to a group in the Domino Directory.

For more information on creating groups, see Administering the Domino System.

372 Application Development with Domino Designer 7


-Default-
Users and servers receive the access assigned to the -Default- group if they have not specifically been
assigned another access level, either individually or as a member of a group, or from a wildcard entry.
You cannot delete the -Default- group from an ACL. The default access for -Default- depends on the
design of the database template and varies among the different templates.

The access level you assign to the -Default- group depends on how secure you want the database to be.
Select No Access if you want a database available to a limited number of users. Select Author or Reader
access to make a database available for general use. The User Type field for -Default- should be set to
″unspecified.″

Database creator user name


The database creator user name is the hierarchical user name of the person who created the database. The
default access for the user who creates the database is Manager. Typically, this person retains Manager
access or is granted Designer access to the database.

LocalDomainServers
The LocalDomainServers group lists the servers in the same domain as the server on which the database
is stored. This group is created by default with every Domino Directory. When you create a new
database, the default access for the LocalDomainServers group is Manager. The group should have at
least Designer access to allow replication of database design changes across the domain. The
LocalDomainServers group is typically given higher access than the OtherDomainServers group.

OtherDomainServers
The OtherDomainServers group lists the servers outside the domain of the server on which the database
is stored. This group is created by default with every Domino Directory. When you create a new
database, the default access for the OtherDomainServers group is No Access to prevent a database from
replicating outside the local domain.

Acceptable entries in the ACL


Acceptable entries in the ACL include:
v Wildcard entries
v User, server, and group names (including user and group names of Internet clients)
v Alternate names
v LDAP users
v Anonymous, which can be used for anonymous Internet user access and anonymous Notes user access
v Database replica IDs

Each entry can have a maximum of 255 characters.

Add names to the ACL in the hierarchical format assigned by the Domino server administrator. For
example:
Sandra E Smith/West/Acme/US

For more information on creating hierarchical name schemes, see Administering the Domino System.

Wildcard entries
To allow general access to a database, you can enter hierarchical names with a wildcard character (*) in
the ACL. You can use wildcards in the common name and organizational unit components.

Users and/or servers who do not already have a specific user or group name entry in the ACL, and
whose hierarchical names include the components that contain a wildcard, are given the highest level of
access specified by every one of the wildcard entries that match.

Chapter 19. Security in an application 373


Here is an ACL entry in wildcard format:

*/Illustration/Production/Acme/US

This entry grants the chosen access level to:

Mary Tsen/Illustration/Production/Acme/US

Michael Bowling/Illustration/Production/Acme/US

This entry does not grant the chosen access level to:

Sandy Braun/Documentation/Production/Acme/US

Alan Nelson/Acme/US

You can use a wildcard only at the leftmost portion of the ACL entry. When you use a wildcard ACL
entry, set the user type in the ACL as Unspecified, Mixed Group, or Person Group.

User names
You can add to an ACL the names of any individuals with certified Notes user IDs or Internet users who
authenticate using name-and-password or SSL client authentication.
v For Notes users, enter the full hierarchical name for each user -- for example, John Smith/Sales/Acme
-- regardless of whether the user is in the same hierarchical organization as the server that stores the
database.
v For Internet users, enter the name that appears as the first entry in the User name field of the Person
document. You can enter multiple alias names in the User name field, but the first entry is used to
perform the security authorization check so it is the first entry that should be used on all Domino
ACLs -- that is, server file and database ACLs.
For more information on database access for anonymous Internet users, see the topic ″Anonymous
access″ later in this chapter.
For more information on setting a maximum level of access for Internet users, see the topic ″Maximum
Internet name-and-password access″ later in this chapter.

Server names
You can add server names to an ACL to control the changes a database receives from a database replica.
To ensure tighter security, use the full hierarchical name of the server -- for example, Server1/Sales/Acme
-- regardless of whether the name of the server being added is in a different hierarchical organization
than that of the server that stores the database.

Group names
You can add a group name -- for example, Training -- to the ACL to represent multiple users or servers
that require the same access. Users must be listed in groups with a primary hierarchical name or an
alternate name. Groups can also have wildcard entries as members. Before you can use a group name in
an ACL, you must create the group in the Domino Directory or in an LDAP directory that has been
configured for group expansion in the Directory Assistance database.

Tip: Use individual names rather than group names for the managers of a database. Then when users
choose Create - Other - Memo to Database Manager, they’ll know whom they are addressing.

Groups provide a convenient way to administer a database ACL. Using a group in the ACL offers the
following advantages:
v You can add one group name instead of adding a long list of individual names to an ACL,. If a group
is listed in more than one ACL, modify the group document in the Domino Directory or the LDAP
Directory, rather than add and delete individual names in multiple databases.

374 Application Development with Domino Designer 7


v You can change the access level for several users or servers at the same time.
v You can use group names to reflect the responsibilities of group members or the organization of a
department or company.

Tip: You can also use groups to let certain users control access to the database without giving them
Manager or Designer access. For example, you can create groups in the Domino Directory for each level
of database access needed, add the groups to the ACL, and allow specific users to own the groups. These
users can then modify the groups, but they can’t modify the database design.

Terminations group
When employees leave an organization, the Domino administrator should remove their names from all
groups in the Domino Directory and add them a terminations group, which is denied access to servers.
Work with your server administrator to make sure that the names of terminated employees are removed
from the ACLs of all databases in your organization. Make sure that the terminations group is added to
the ACLs and that the group is assigned No Access.

You can also use the Deny Access group for this purpose. The Deny Access group contains the names of
Notes users who no longer have access to Domino servers. When you delete a person from the Domino
Directory, you have the option to ″Add deleted user to deny access group,″ if such a group has been
created. (If no such group exists, the dialog box displays ″No Deny Access group selected or available.″)

For more information on the Deny Access group, see Administering the Domino System.

Alternate names
An alternate name is an optional alias name that an administrator assigns to a registered Notes user,
often to publish a name in two different character sets, such as English and Kanji. You can add alternate
names to an ACL. An alternate name provides the same level of security as the user’s primary
hierarchical name. An example of a user name in alternate name format is Sandy
Smith/ANWest/ANSales/ANAcme, where AN is an alternate name.

LDAP users
You can use a secondary LDAP directory to authenticate Web users. You can then add the names of these
Internet users to database ACLs to control user access to databases.

You can also create groups in the secondary LDAP directory that include the Internet user names and
then add the groups as entries in Notes database ACLs. For example, an Internet user may try to access a
database on a Domino Web server. If the Web server authenticates the user, and if the ACL contains a
group named ″Web,″ the server can look up the Web user’s name in the group ″Web″ located in the
foreign LDAP directory, in addition to searching for the entry in the primary Domino Directory. Note that
for this scenario to work, the Directory Assistance database on the Web server must include an LDAP
Directory Assistance document for the LDAP directory with the Group Expansion option enabled. You
can also use this feature to look up the names of Notes users stored in foreign LDAP directory groups for
database ACL checking.

When you add the name of an LDAP directory user or group to a database ACL, use the LDAP format
for the name, but use a forward slash (/), rather than a comma (,), as a delimiter. For example, if the
name of a user in the LDAP directory is:

uid=Sandra Smith,o=Acme,c=US

enter the following in the database ACL:

uid=Sandra Smith/o=Acme/c=US

To enter the name of a non-hierarchical LDAP directory group in an ACL, enter only the attribute value,
not the attribute name. For example, if the non-hierarchical name of the LDAP group is:

Chapter 19. Security in an application 375


cn=managers

in the ACL enter only:

managers

To enter the name of a hierarchical group name, include LDAP attribute names in ACL entries. For
example, if the hierarchical name of the group is:

cn=managers,o=acme

in the ACL enter:

cn=managers/o=acme

Note that if the attribute names you specify correspond exactly to those used in Notes -- cn, ou, o, c -- the
ACL won’t display the attributes.

For example, if you enter this name in an ACL:

cn=Sandra Smith/ou=West/o=Acme/c=US

because the attributes correspond exactly to those used by Notes, the name appears in the ACL as:

Sandra Smith/West/Acme/US

Anonymous access
Anonymous database access is given to Internet users and to Notes users who have not authenticated
with the server. You can control the level of database access granted to an anonymous user or server by
entering the name Anonymous in the access control list, and assigning an appropriate level of access.
Typically you assign Anonymous users Reader access to a database.

The table below describes different ways that an anonymous user can access a database:

Anonymous access enabled for Anonymous access not enabled for


Access specified Internet protocol Internet protocol
Anonymous access enabled in Users access the database with the Users are prompted to authenticate
database ACL Anonymous entry’s access level. For when they attempt to access any
example, if Anonymous access is set resource on the server. If the user is
to Reader, anonymous users who not listed in the database (through a
access the database have Reader group entry, a wildcard entry, or if the
access. user name is explicitly listed), then
the user accesses the database with
the -Default- entry’s access level.
Anonymous not listed in database Anonymous users access the
ACL database with the -Default- entry’s
access level. For example, if -Default-
access is set to Reader, and there is
no Anonymous entry in the ACL,
anonymous users who access the
database have Reader access.

376 Application Development with Domino Designer 7


Anonymous access enabled for Anonymous access not enabled for
Access specified Internet protocol Internet protocol
Anonymous assigned ″No Access″ in Users will be prompted to
database ACL authenticate when they attempt to
Note: ″Read and write public access this database. When
documents″ privileges should be authenticated they will be granted
disabled the appropriate access level assigned
in the ACL.

Anonymous users (both those who are given access to a database through the Anonymous entry and
those who have access through the -Default- entry) who try to do something that is not allowed for their
access level will be prompted to authenticate. For example, if Anonymous is set to Reader, and an
anonymous user tries to create a new document, that user is prompted to authenticate with a name and
password.

Tip: If you want all users to authenticate with a database, make sure that Anonymous is in the database
ACL with an access level of No Access, and add the Internet user’s name to the ACL with the level of
access you want the user to have. You should also be sure that the Read Public Documents and Write
Public Documents privileges are not enabled in the database ACL.

The Domino server uses the group name Anonymous solely for access control checks. For example, if
Anonymous has Author access in the database ACL, the true name of the user appears in the Authors
field of documents the user creates in the database. The Domino server can display only the true name of
anonymous Notes users, but not of anonymous Web users, in the Authors field of the document. Authors
fields are never a security feature, regardless if anonymous access is used; if the validity of the author’s
name is needed for security, then the document should be signed.

Replica IDs
To allow an agent in one database to use @DbColumn or @DbLookup to retrieve data from another
database, enter the replica ID of the database containing the agent in the ACL of the database containing
the data to be retrieved. The database containing the agent must have at least Reader access to the
database containing the data to be retrieved. Both databases must be on the same server. An example of a
replica ID in a database ACL is 85255B42:005A8fA4.

If you do not add the replica ID to the access control list, the other database can still retrieve data if the
-Default- access level of your database is Reader or higher.

To determine the replica ID of a database, choose File - Database - Properties, and click the Info (i) tab.
Or choose File - Database - Design Synopsis, and select Replication.

To add a replica ID to the ACL


Type or copy and paste the replica ID from the Design Synopsis dialog box into the ACL or type the
replica ID you get from the info (i) tab of the Database properties box. You can type the replica ID in
uppercase or lowercase characters, but do not enclose it in quotation marks.

Order of evaluation for ACL entries


ACL entries are evaluated in a specific order to determine the access level that will be granted to an
authenticated Notes user trying to access the database.
v The ACL first checks the user name to see if it matches any of the ACL entries. The ACL checks all
matching user names. For example, Sandra E Smith/West/Acme would match the entries Sandra E
Smith/West/Acme/US and Sandra E Smith. In the event that two different entries for an individual
have different access levels (for example, applied at different times by different administrators), the
user trying to access the database would be granted the highest access level, as well as the union the
access privileges of the two entries for that user in the ACL. This can also happen if the user has
alternate names.

Chapter 19. Security in an application 377


Note: If you enter only the common name in the ACL (for example, Sandra E Smith), then that entry
matches only if the user’s name and the database server are in the same domain hierarchy. For
example, if the user is Sandra E Smith, whose hierarchical name is Sandra E Smith/West/Acme, and
the database server is Manufacturing/FactoryCo, then the entry Sandra E Smith will not get the correct
level of access for ACLs on the server Manufacturing/FactoryCo. The name must be entered in full
hierarchical format in order for the user to obtain the correct level of access to ACLs on servers in
other domains.
v If no match is made on the user name, the ACL then checks to see if there is a group name entry that
can be matched. If an individual trying to access the database happens to match more than one group
entry -- for example, if the person is a member of Sales and the two group entries for Sales are
Sales/West/Acme and Sales/Acme -- then the individual is granted the highest access level, as well as
the union of the access privileges of the two entries for that group in the ACL.

Note: If the user matches an explicit entry in the ACL, and is a member of a group that is also listed
in the ACL, then the user always gets the level of access assigned to the explicit entry, even if the
group access level is higher.
v If no match is made on the group name, the ACL then checks to see if there is a wildcard entry that
can be matched. If the individual trying to access the database happens to match more than one
wildcard entry, the individual is granted the highest access level, as well as the union of the access
privileges of all the wildcard entries that match.
v If a group entry and a wildcard entry both apply to a user attempting to access the database, then the
user has the access assigned to the group entry. For example, if the group Sales has Reader access and
the wildcard entry */west/Acme has Manager access, and both entries apply to a user, then the user
has Reader access to the database.
v If no match can be made from among the database ACL entries, the individual is granted the level of
access defined for the -Default- entry.

User types in the ACL


A user type identifies whether a name in the ACL is for a person, server, or group. When you assign a
user type to a name, you specify the type of ID required for accessing the database with that name. The
user types are Person, Server, Mixed Group, Person Group, Server Group, and Unspecified. The -Default-
group in the ACL is always assigned Unspecified as the user type.

User types provide additional security for a database. For example, assigning the Person user type to a
name other than ’″unspecified″ prevents an unauthorized user from creating a Group document with the
same person name, adding his or her name to the group, and then accessing the database through the
group name.

Designating a name as a Server or Server Group prevents a user from using the server ID at a
workstation to access a database on the server. Be aware, though, that designating a name as a Server or
Server Group is not a foolproof security method. It is possible for a user to create an add-in program that
acts like a server and uses a server ID to access the server database from a workstation.

Instead of manually assigning a user type to each name, you can automatically assign a user type to all
unassigned names in the ACL. The user type assigned to each name is determined by the Domino
Directory entry for that name. Using this method, a group is always designated as Mixed Group, and not
as a Person Group or a Server Group. To assign a Person Group or Server Group to a name, you must
select the name and manually assign that user type.

To manually assign a user type to a name


1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmarks pane.
3. Choose File - Database - Access Control.
4. Select a name to which you want to assign a user type.

378 Application Development with Domino Designer 7


5. Select a user type and click OK.

To automatically assign user types to unspecified users


1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmarks pane.
3. Choose File - Database - Access Control.
4. Click the Advanced icon.
5. Click ″Look Up User Types for ’Unspecified’ Users.″
6. Click OK.

Enforcing a consistent access control list


You can ensure that an ACL remains identical on all database replicas on servers, as well as on all local
replicas that users make on workstations or laptops.

Select the ″Enforce a consistent Access Control List″ setting on a replica whose server has Manager access
to other replicas to keep the access control list the same across all server replicas of a database. If you
select a replica whose server does not have Manager access to other replicas, replication fails because the
server has inadequate access to replicate the ACL.

If a user replicates a database locally, the database ACL recognizes that user’s access as it is known to the
server. This happens automatically for local replication, regardless of whether ″Enforce a consistent
Access Control List″ is enabled.

Note: Local replicas with ″Enforce a consistent Access Control List″ enabled attempt to honor the
information in the ACL and determine who can do what accordingly. However, they have some
limitations. One limitation is that group information is generated on the server, not at the local replica.
When a database is replicated locally, information about the group membership of the person doing the
replication is stored in the database for use in ACL checking. If a person/identity other than the one
doing the replication accesses the local replica, there will be no group membership information available
for that person, and the ACL can use only the person’s identity, not group membership, to check access.

Additionally, enforcing a consistent access control list does not provide security for local replicas. To keep
data in local replicas secure, encrypt the database on the Database Basics tab of the Database properties
box.

Note: If a user changes a local or remote server database replica’s ACL when the ″Enforce a consistent
Access Control List″ option is selected, the database stops replicating. The log (LOG.NSF) records a
message indicating that replication could not proceed because the program could not maintain a uniform
ACL on replicas.

To enforce or disable a consistent access control list


Use this method to enforce or disable a consistent ACL for a single database.
1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmarks pane. If the database has multiple replicas, select the
database icon from a server that has Manager access in the database ACL of the other replicas.
3. Choose File - Database - Access Control.
4. Click Advanced.
5. Do one of the following:
v To enforce a consistent ACL, select ″Enforce a consistent Access Control List across all replicas of
this database.″
v To disable a consistent ACL, deselect ″Enforce a consistent Access Control List across all replicas of
this database.″

Chapter 19. Security in an application 379


6. Click OK.

Displaying the ACL history


You can display a chronological history of changes made to a database ACL. Each entry in the list shows
when the change occurred, who made the change, and what changed. The history stores only 20 lines of
changes, not the complete history.
1. Select the database icon from your Bookmarks pane.
2. Choose File - Database - Access Control.
3. Click Log.
4. Select a line of log history. To see the complete text of the log history, look in the field at the bottom
of the dialog box.
5. (Optional) Click Copy to copy the ACL history to the clipboard so that you can paste it in a
document.

To display a name’s effective access


The ″effective″ access a person, server, or a group has to documents in a database is not always apparent.
For example, if there are two groups with different levels of access to documents, and someone is a
member of both groups, you may wonder what access the person actually has. You can determine a
person’s effective access to the documents from the ACL.
1. Select a database and choose File - Database - Access Control.
2. Click ″Effective Access.″
3. From the Effective Access dialog box, select the name of the person, server, or and press Enter or click
″Calculate Access.″
″Database Access is derived from″ in the top left of the dialog box shows the selected name’s effective
database access as determined by the database ACL.
The checked boxes on the lower left of the dialog box indicate the access rights for the selected name.
The ″Groups″ and ″Roles″ boxes on the right of the dialog box show all the individual and group
name entries and roles that could potentially control the selected name’s access to the selected
document. If the person, server, or group is not in the ACL, the ″Groups″ box displays the group used
to determine the effective access.
4. After you review the effective access for the selected name, click Done.

It’s possible to assign users or servers more than one level of access to a database. The following table
describes the order of precedence for competing access levels.

Access level conflict Resolution


A name is listed in an ACL individually and as a The access level assigned to the individual name takes
member of a group precedence over the access level for the group, even if the
individual access level is lower than the group level.
A name is included in two or more groups The name receives the access of the group with the
highest access.
A name appears in an ACL and in access lists The ACL controls database access; design element access
associated with forms, views, or sections lists refine this access to a lower level. For example, if a
user has Author access to a database but is not listed in
the access list for a form in the database, the user cannot
use the form to create a document.

Security overview for Web applications


When you set up database access, you must make special provisions for Internet users. See the following
topics for information about setting up and controlling the access that Internet users have to a database:

380 Application Development with Domino Designer 7


Application access for Web users

Enforcing encrypted Web transactions using SSL

Maximum Internet and password access

Examples of ACL setting for a Web database

Application access for Web users


The Advanced section of the ACL lets you specify a maximum access setting for Internet users who are
authenticated with Basic authentication (that is, name and password, and also with Sessions-based
authentication for HTTP only). You can limit access to what you specify as the ″Maximum Internet name
& password access.″ The ″Maximum Internet name & password access″ field does NOT apply to Internet
users authenticated using Secure Socket Layer (SSL) Client certificates. These users have the full access
granted to them in the ACL.

For information on setting up SSL, see ″Enforcing encrypted Web transactions using SSL,″ later in this
chapter.

Using Java technologies, you can share code with and link to WebSphere applications. Single Sign-On
(SSO) -- a shared authentication service -- allows for further seamless integration between Domino and
WebSphere applications. For information on Single Sign-On, see Administering the Domino System.

Default logout time period: You can specify a default logout time period to log the Web client off the
server after a specified period of inactivity. This forces the cookie that Domino uses to track the user
session to expire. Automatically logging a user off the server prevents others from using the Web client to
impersonate a user if the user leaves the workstation before logging off. If you enable session-based
name-and-password authentication for a server, users can also append ?logout at the end of a URL to log
off a session -- for example:
"http://acmeserver/sessions.nsf?logout."http://acmeserver/sessions.nsf?logout

You can also redirect the logout to a design element or URL using the &RedirectTo parameter. For
example:
"Http://acmeserver/sessions.nsf?logout&redirectto=/logoutDB.nsf/logoutApp?Open"http://acmeserver/
sessions.nsf?logout&redirectto=/logoutDB.nsf/logoutApp?OpenPage
Http://acmeserver/sessions.nsf?logout&redirectto=http://www.sales.com

You can build this expression into an application -- for example, using it in a button -- or type it in as a
URL.

Enforcing encrypted Web transactions using SSL


The Secure Sockets Layer (SSL) is a security protocol that protects data by encrypting it as it passes
between servers and Web clients. SSL provides communications privacy and authentication for Domino
server tasks that operate over TCP/IP. You can require users to access a database using a secure SSL
connection to a single database or to all databases on a server. A common use for this type of added
security occurs in an e-commerce application in which Web users enter confidential information such as
credit card numbers.

If you do not require an SSL connection, clients can use either SSL or TCP/IP to connect to the server.

The server administrator enables the SSL port in either the Internet Site document or the Server
document of the Domino Directory. Then, to protect transactions in individual databases -- for example,
in databases used for commercial transactions -- the database designer assigns the database property
″Web Access: Require SSL Connection.″

For more information on SSL certificates, see Administering the Domino System.

Chapter 19. Security in an application 381


Note that the server administrator actually has three options in allowing access over the SSL port:
v With anonymous access over the SSL port -- Web users can connect to the server using the SSL port,
however, the server allows anonymous users.
v With name and password access -- Web users connect to the server over the SSL port, and authenticate
using name and password.
v With access through client certificates -- Web users have been issued an X.509 client certificate and
connect to the server over the SSL port. They are authenticated using this client certificate.

To require an SSL connection to a database:


1. Make sure you have Manager access in the database ACL.
2. Select the database icon from the bookmarks page.
3. Choose File - Database - Properties.
4. On the Basics tab, choose Web access: Require SSL connection.
For more information, see Administering the Domino System.

Maximum Internet name-and-password access


Users who have Internet or intranet browser access to a database cannot be identified by Notes in the
same way Notes users are identified. Use the ″Maximum Internet name & password access″ setting in the
ACL to control the maximum type of access that Internet or intranet browser users have to a database.
The list of available access levels mirrors the standard access levels for Notes users.

This setting applies to users who use name-and-password authentication or access the server
anonymously over the Internet and connect to servers using either the TCP/IP port or the SSL port. This
setting does not apply to users who have SSL client certificate IDs and who access the database over the
Internet on the SSL port. Users with SSL client access receive the level of access specified in the database
ACL.

Add an entry for the group Anonymous to the database ACL, if appropriate for this database. Then select
the maximum access level you want to assign to all Internet and intranet users who use
name-and-password authentication for a particular database. Users who access a Notes database over the
Internet, either anonymously or by using name-and-password authentication, never have an access level
higher than what is specified as the ″Maximum Internet name & password access″ level.

CAUTION:
The ″Maximum″ access level overrides the access level that a user may have been explicitly given in
the database ACL.

For example, a user, Sandra Smith/West/Sales/Acme, can use a name and password to access a server
using a Web browser. If Sandra Smith/West/Sales/Acme is assigned Editor access in the ACL and the
″Maximum Internet name & password access″ setting is Reader, the lower of the two access levels applies
and Sandra is allowed only Reader access. Similarly, if Sandra Smith/West/Sales/Acme is assigned
Reader access in the ACL and the ″Maximum″ access setting is Editor, Sandra is allowed only Reader
access. If Sandra Smith also uses a Notes client to access the database, the ″Maximum″ access setting is
ignored and Sandra is allowed Editor access.

The default for this option is Editor access. Tasks such as creating folders, views, and agents, do not
apply to Internet users.

Tip: You can use this setting to prevent Internet users from accessing the database using
name-and-password authentication. By setting it to ″No Access,″ the database is accessible only to Notes
users or Internet users who authenticate using SSL client certificates.

To select the maximum Internet name and password: Use this method to select the maximum Internet
name-and-password access for a single database.

382 Application Development with Domino Designer 7


1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your bookmarks page.
3. Select File - Database - Access Control.
4. Click Advanced.
5. Select the maximum access level from the list next to the field ″Maximum Internet name & password.″
6. Click OK.

Application design element security


An application developer can restrict access to design elements within an application. Application design
security takes effect when users gain access to an application.

Create To
Read access lists for views Specify which Notes and Internet users can see a view.
Read and Edit access lists for folders Specify which Notes and Internet users can see a folder or
update the contents of a folder.
Read and Edit access lists for forms Specify which Notes and Internet users can create, modify,
or read documents created with a form.
Readers and Authors fields Specify which Notes and Internet users can create, modify,
or read specified documents.
Signed fields Verify that the Notes user who originated the data is the
author and that no one has tampered with the data.
Encrypted fields Control which Notes users can access a field in a form.
Note: Encryption is not supported in Web applications.
Hidden fields Control which Notes and Internet users can access a field in
a form.
Read and Edit access lists for sections Specify which Notes and Internet users can access a section
in a document.
Restrict who can create agents and where the agents can
run.
Secure the design of a database to prevent users from
changing design elements.

For information on restricting agents, see the chapter, ″Automation in Applications.″

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 and other designers have access to the database. When the database is ready to be released, you can
adjust access control settings to provide general access to the application.

When you create a database, you are assigned as the Manager of that database by default. This gives you
complete access rights. You can then designate others as designers so they can contribute to the design.

To keep a database private during development


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

Chapter 19. Security in an application 383


6. Deselect ″Show in ’Open Database’ Dialog.″

For more information on access control, see The database access control list.

Restricting who can read or edit documents


To restrict who can read documents, add a Readers field to a form. To restrict who can edit a document,
add an create, add an Authors field to a form, which allows only users who have Author access in the
ACL to edit the documents they create.

Note: Readers and Authors fields take effect only when the database is on a server. If you develop a
database locally, you can’t test this feature until you copy the database to a server.

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. Without Reader access to a
document, a user cannot see the document in a view. For example, to limit access to an employee’s
personnel file to members of the Human Resources department, the employee, and the employee’s
manager, list those people in a Readers field.

If a form has a read access list, names from the Readers field are added to the access list. Otherwise, the
Readers field controls access to documents created from the form.

Entries in a Readers field cannot give a user more access than what is specified in the database access
control list (ACL); they can only further restrict access. Users who have been assigned ″No Access″ to a
database in the ACL can never read a document, even if you list them in a Readers field. On the other
hand, users with Editor access or above in the ACL can be restricted from reading documents if they
aren’t included in a Readers field.

Any users who have Editor (or higher) access to the database can read and edit a document if one of the
following is true:
v They are listed in the form’s Read access list or Readers field.
v The form has no Read access list restrictions or no Readers field.
For information on creating a Reader’s field, see ″To create Readers and Authors fields″ later in this
chapter.
For information on updating Readers fields, see Administering the Domino System.

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 users
Author access in the ACL, they can read documents in the database but cannot edit their own
documents. If you list those users in an Authors field, they can edit documents in the database.

Entries in an Authors field cannot override the database ACL; they can only refine it. Users who have
been assigned No Access in an ACL can never edit a document, even if you list them in an Authors field.
Users who already have Editor (or higher) access in the ACL are not affected by an Authors field.
Authors fields affect only users who have Author access in the ACL.

You must enter the user’s full hierarchical name in the Authors field.
v If you manually enter a name in the Authors field, Domino expands and stores, for example, John
Smith/ACME/West is stored as (CN=John Smith/OU=ACME/O=West) in its hierarchical form. The
name displays in its abbreviated form.
v If you programmatically enter a name, you must use the full canonical form such as CN=John
Smith/OU=ACME/O=West.

384 Application Development with Domino Designer 7


For information on creating an Author’s field, see ″To create Readers and Authors fields″ later in this
chapter
For information on updating Authors fields, see Administering the Domino System.

To create Readers and Authors fields


Restrict Read access to documents by creating Readers and Authors fields as follows.
1. Open the form in Designer.
2. Create a field, or click an existing field. Then choose Design - Field Properties.
3. On the Field Info(i) tab, select Readers or Authors as the type, and then:
v Select Editable to allow authors and editors to modify the list. (Be sure to include yourself in the
default value formulas, which you create in the Script area of the Programmer’s pane -- so there is
at least one value.)
v Select Computed to write a formula that computes the reader or author names.
Writing formulas for Readers and Authors fields
When you write a formula for a Readers or Authors field, enclose user names and group names in
quotation marks.
"Marketing"
Select ″Allow multi-values″ for a field that stores a text list with multiple names. Concatenate the
names in the formula with a colon.
"Mary Sen":"Marketing":"Joyce O’Connor"
Place quotation marks and square brackets around role names that qualify access levels.
"[Scheduling Committee]"
4. To create editable or computed field values, click the Programmer’s pane, select a formula type, and
write the formula; click the green check mark to save the formula.

Note: Include server names in the formula if the database will replicate.
5. On the Control tab, choose one of the following options to generate a list of readers or authors from
which users can select.

Note: Unless ″None″ is selected as the lookup option for a Readers or Authors field, users press
either CTRL+ENTER or, if specified for the field, the entry helper button to see a list of possible
entries. If the Readers field is located inside a layout region, leave ″None″ selected; other lookup
options do not apply.
v Use None to 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. Domino fills in the first name that
matches the characters the user types.
v Use Address dialog box for choices to display the Names dialog box so users can select names from
a Personal Address Book or from the Domino Directory. Select ″Look up names as each character is
entered″ to help users fill in a name quickly and Designer looks up a match.
v Use access control list for choices to display a list of people, servers, groups, and roles in the ACL.
v Use View dialog box for choices to display a dialog box containing entries from a column in a
Designer database view. Select the database to look up, select a view, and select a column number.
6. (Optional) On the Field Info tab, select ″Allow multi-values″ to allow more than one name to be
stored in the field.
7. (Optional) On the Control tab, select ″Allow values not in list″ to let users enter additional names.
This property is applicable only to Address and Access Control List choices.
8. Save and close the form.

Note: When you specify names for reader and author fields, use the full hierarchical name for each user
if there is a chance this database will be copied or replicated to another domain. Within a domain, an

Chapter 19. Security in an application 385


abbreviated, or common name, is sufficient for user authentication, but between domains, you must
supply the full hierarchical name or authentication will fail.

Tracking who edits a document


If a document contains an Authors field, Designer automatically stores the names of the users who have
edited that document in an internal field called $UpdatedBy. Servers involved in replication are not
considered editors, so they’re not tracked in this list.

To display the contents of the $UpdatedBy field, users can click and hold the cursor on the Authors field
in a document they’re reading. Designer displays a pop-up list 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.

If a form is assigned the ″Anonymous form″ property, its documents do not contain an $UpdatedBy field;
instead, the documents contain an $Anonymous field with a value of ″1.″

Updating Readers and Authors fields


By default, the Administration Process examines all documents in a database to find and update Readers
and Authors fields and to update private views, folders, and agents. When the Administration Process
performs a ″Rename person″ or a ″Delete person″ request, it edits or removes the name in all Readers
and Authors fields and in private folders, views, and agents. To update Readers and Authors fields in
only selected documents, you create a special view in the database and then update that view.

You must select an administration server if you want to select the option to modify Readers and Authors
fields. The default is to not modify Readers and Authors fields.

To update Readers and Authors fields in all documents


Use this method to modify Readers and Authors fields for a single database.
1. Make sure that you have:
v Manager access in the database ACL
v already specified an administration server for the database.
2. Select the database icon from your Bookmark pane.
3. Choose File - Database - Access Control.
4. Click the Advanced icon.
5. Below ″Administration Server,″ select Server.
6. Select an administration server, and then click OK.
7. Select ″Modify all Reader and Author fields″ from the list below ″Administration Server.″
8. Click OK.

To update Readers and Authors fields in selected documents


1. Create a new view in the database and name the view $Adminp.
2. Write a view selection formula that selects and displays only the documents containing the fields to
update.
3. Select the database icon from your Bookmark pane.
4. Choose File - Database - Access Control.
5. Click the Advanced icon.
6. Below ″Administration Server,″ select Server.
7. Select an administration server, and then click OK.
8. Select ″Modify all Reader and Author fields″ from the list below ″Administration Server.″
9. Click OK.

386 Application Development with Domino Designer 7


For more information on the Administration Process (adminp), see Administering the Domino System.

For more information on creating views and writing view selection formulas, see Creating a standard
view.

Setting up the Administration Process for databases


To use the Administration Process (adminp) to update and manage names in an ACL and in Readers and
Authors fields, you must assign an administration server to the database.
1. Make sure that you have Manager access in the database ACL.
2. Select the database icon from your Bookmark pane.
3. Choose File - Database - Access Control.
4. Click the Advanced icon.
5. Below Administration Server, select Server.
6. Select an administration server from the list, and click OK.

Note: When Notes users create databases, they can specify the administration server for their databases
on the Advanced panel of the database ACL. The database ACL list is automatically updated when the
adminp process is run on the specified administration server.

For more information on the Administration Process (adminp), see Administering the Domino System.

Creating controlled-access sections of forms


You can control access to parts of documents by creating access-controlled sections on forms that allow
specified users to see restricted parts of documents.

To create a controlled-access section


1. Highlight the text, fields, and other design elements on a form that make up the section.
2. Choose Create - Section - Controlled Access.
3. (Optional) In the Section Properties box on the Section Title and Border tab, edit the section title.
4. (Optional) Enter a Section Field Name.
5. (Optional) Choose a border style and border color for the section.

You can insert fields and other design elements into the section after creating it. To append design
elements to the bottom of the section, set the border style as a box. When you have finished appending
design elements, set the border style to no border.

To name the editors for a controlled-access section


1. Click the section title.
2. Choose Section - Section Properties.
3. Click the Formula tab.
4. Select Editable as the section type to allow the document creator to specify the section editors.
5. Select one of the Computed types to use a formula to define the section editors.
6. (Optional for an editable field; Required for a computed field) In the Properties box, write a formula
to define who can edit the field, and click the check mark. (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
check mark.

Note: When you specify names for section editors, use the full hierarchical name for each user if there is
a chance this database will be copied or replicated to another domain. Within a domain, an abbreviated,
or common name, is sufficient for user authentication, but between domains, you must supply the full
hierarchical name or authentication will fail.

Chapter 19. Security in an application 387


To make a controlled-access section collapsible
1. Click the section marker and choose Section - Section Properties.
2. Click the Expand/Collapse tab and select options for showing the section expanded or collapsed,
depending on whether a document is being previewed, printed, or opened.
3. On the same tab, click the ″For Editors″ list and select ″For Non-editors.″ A list of options appears for
displaying the section to users who can read but not edit the section.
4. (Optional) Select ″Hide title when expanded″ if users who are non-editors don’t need to see the
section title when the fields are displayed.
5. Save and close the form.

Examples of access-controlled sections


The following examples illustrate different uses for access-controlled sections on forms.

Computing an editors list from the access control list


The status section of a Business Card Request form has a controlled-access section whose formula allows
only administrators (an access role in the ACL) 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 a controlled-access section whose default value formula
always allows the author to edit the status report. Users who have access to the document but are not the
author can read the section but cannot edit it.
"@Author"

The author can choose Section - Define Editors to name additional editors for a particular status report.

Limiting Editor access to sections of forms


In workflow applications, use sections to restrict who can edit or sign parts of a document. If a document
requires more than one approval signature, you create a section on the form for each signature or group.
For example, you might create a section specifically for the Purchasing group.

Edit access lists and the access control list


To specify who can edit parts of a section, select the fields you want to restrict and create a section
containing the fields. Then specify who can edit the fields in one of the following ways:
v Let the author of the document choose who can edit the section.
v Specify the users, groups, or roles who can edit the section.

For users who are not listed as editors of the section, the fields appear as read-only. Editor access of the
section does not override Editor access in the database access control list (ACL); it only refines it.
Privilege names cannot be used in the Edit access list.

Tip: If you use custom roles to refine standard access levels, consider creating a section that corresponds
to each access role. Then create a field named RoleName at the top of the section.

Using a computed field to define section editors


To define a list of section editors, write a formula that populates the list of allowed editors, by including
the current user’s name, using @DbColumn to retrieve a list of names, using the value of an approver
field, or using a group name or role from the ACL. Use a computed-when-composed field to create a
permanent list of editors when a document is created.

388 Application Development with Domino Designer 7


You can use only formulas that result in a text list containing one or more names; you can then append
the names to the section’s edit access list. Enclose the names in quotation marks and concatenate them
with a colon ( : ).

″Mary Sen″:″Marketing Group″

Access role names must include square brackets and be enclosed in quotation marks:

″[Scheduling Committee]″

For information on using database lookups, see the Programming 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.

An editable section allows the author of each document 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 a controlled-access section on multiple forms


To use a controlled-access section on more than one form, place the section on a subform and include the
subform in the forms.

Creating read access lists to limit view and folder access


To allow some users and not others to see a view or folder, create a read access list. Users who are
excluded from the access list do not see the view or folder on the View menu. A view or folder read
access list is not a true security measure. Unless the documents are otherwise protected, users can create
private views and folders that display the documents shown in the restricted view. 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.
2. Choose Design - View Properties or Design - Folder Properties.
3. Click the Security tab.
4. Deselect ″All readers and above.″
5. Click each user, group, server, or access role you want to include. A check mark appears next to each
selected name.
6. Click the Person icon to add person or group names from a Personal Address Book or from the
Domino Directory.
7. To remove a name from the list, click the name again to remove the check mark.
8. (Optional) Check ″Available to Public Access Users″ if you want this view or folder available to users
with public access read or write privileges in the access control list for this database.
9. Save the view or folder.

Notes
v Do not create a read access list for the default view of a database.

Chapter 19. Security in an application 389


v Servers that need to replicate a database need access to views that are read-restricted so that view
design changes can replicate.

Example of restricting access to a view


To improve the performance of the Technical Services, Rajeev Jain designed a ″Tech Services Review″
form, which is included in the company’s 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, because there is no group in the Domino
Directory for the people he wants to include in the access list, Rajeev defines an access role called
[TSMAnagers] in the database ACL, and adds that role to the view’s read access list. The access role is
stored within the Service Request Tracking database; it is not added to the Domino Directory.

Creating write access lists to limit folder access


To allow some users and not others to update the contents of a folder, create a write access list for the
folder. You can add users to a write access list for a folder as long as the users already have at least
Author access in the database access control list. Users specified in the write access list for the folder can
move and copy documents into the folder and can remove documents from the folder. With only Author
access, they cannot edit documents in the folder.
1. Select a database.
2. In the Design pane, click Folders.
3. Double-click the view or folder in the Work pane.
4. Choose Design - Folder Properties.
5. Click the Security tab.
6. In the ″Contents can be updated by:″ section, deselect ″All Authors and above.″
7. Do any of the following:
v Click each user, group, server, or access role you want to include. A check mark appears next to
each selected name.
v Click the Person icon to add person or group names from a Personal Address Book or from the
Domino Directory.
v To remove a name from the list, click the name again to remove the check mark.
8. Save the folder.

Access-controlled forms and documents


To restrict access to all or part of a form, and to all documents created from a form, you can create a form
read access or a create access list.

Create access list


Use a create access list to limit who can access the form in order to create. Limiting who can create
documents from a form also shortens the create menu by removing the restricted forms from the menu.

Read access list


Use a read access list to limit who can read documents created from a form. For example, you might use
a read access list to restrict access containing personnel information.

The following people can read a document that has restricted Read access:
v Users assigned Read access in the form access list
v Users listed in the form’s Readers field
Readers field names are added to a document’s read access list.

390 Application Development with Domino Designer 7


v Users listed in the form’s Author’s field

Note: When you use 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 provides an additional measure of
access control in conjunction with the database access control list. However, note that using
access-controlled forms is not a true security measure because a user can create a copy of the form and
remove the restriction.

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 won’t replicate.

To create access-controlled forms


1. Open the form.
2. Choose Design - Form Properties.
3. Click the Security tab.
4. Deselect ″All authors and above″ in the ″Who can create documents with this form″ section.
5. Click each user, group, server, and access role you want to include.
6. Deselect ″All readers and above″ in the ″Default read access for documents created with this form″
section.
7. Click each user, group, server, and access role you want to include.
8. (Optional) Check ″Available to Public Access users″ if you want documents in this view or folder
available to users with public access read or write privileges in the access control list for this database.

To prevent 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 because users can circumvent it by using screen capture programs.
1. Open the form.
2. Choose Design - Form Properties.
3. Click the Security tab.
4. Click ″Disable printing/forwarding/copying to clipboard.″

To prevent editing of existing documents


You can prevent users with Author access in the database ACL from editing a field in existing
documents. This restriction doesn’t apply to new documents.
1. Open the form.
2. Create a field, or click an existing field.
3. In the Field Properties box, click the Advanced tab.
4. Select ″Security options: Must have at least Editor access to use″ and click the check mark.

Creating public access pages, forms, subforms, outlines, views,


agents, and style sheets
The database ACL controls access to specific design elements, such as pages, documents, forms, outlines,
views, folders, and style sheets. Users with No Access or Depositor access in the ACL cannot access the
design elements of a database. There are times, however, when you might want to make design elements
accessible to all users, regardless of access level. To do so, you make the design elements available for
Public Access.

Chapter 19. Security in an application 391


For example, public documents are necessary for calendar applications where one user lets another user
read or create appointments on his or her behalf. To create the public documents for this application, you
must first create a public access form containing a public access field. Then you create a public folder or
view to display the document.

Note that you can also make manually run agents available for public access.

To designate a page, form, or subform for public access


1. Open the page, form, or subform.
2. Choose Design - <design element> Properties.
3. Click the Security tab.
4. Select ″Available to Public Access Users.″
5. On a form or subform, create a field.
6. In the Name field, enter $PublicAccess.
7. In the Type field, select Text and Computed when composed.
8. In the Programmer’s pane at the bottom of the form, enter ″1″ as the default value for the field.
9. To hide this field from users, select the Field Hide When tab and specify hide-when conditions.

To designate a view for public access


1. Open the view.
2. Choose Design - View Properties.
3. Click the Security tab.
4. Check ″Available to public access users″ if you want to make documents in this view or folder
available to users with public access read or write privileges in the access control list for this database.

To designate an outline for public access


1. Open the outline
2. Choose Design - Outline Properties.
3. Check ″Available to public access users.″

To create a style sheet for public access


1. Click Shared Resources - Style Sheets in the Design pane.
2. Highlight a style sheet and choose Resource - Resource Properties. The Style Sheet Resource
Properties box appears.
3. Select the Security tab and check ″Available to public access users.″

To create an agent for public access


1. Open the agent in Designer.
2. Click Options.
3. Select ″Available to Public Access Users.″

Notes and Domino encryption


Encryption is a digital security mechanism that protects data from unauthorized access. Encryption
protects data from unauthorized access. Using Notes and Domino, you can encrypt:
v Messages sent to other users. Then an unauthorized user cannot read the message while it is in transit
or in the recipient’s mail file. You can also encrypt saved and incoming messages.
v Network ports. Encrypting information sent between a Notes workstation and a Domino server, or
between two Domino servers, prevents unauthorized users from reading the data while it is in transit.

392 Application Development with Domino Designer 7


v SSL transactions. Server administrators can use SSL to encrypt information sent between an Internet
client, such as a Notes client, and an Internet server, to prevent unauthorized users from reading the
data while it is in transit.
v Fields, documents, and databases. You can encrypt fields within a document, an entire document, and
local databases. Then only the specified users can read the information.
For information on the first three items, see Administering the Domino System.

Database encryption
Database encryption is designed to prevent unauthorized access to locally stored databases and is not
intended as a replacement for field-level encryption. Database encryption provides an additional layer of
security because ACL settings do not protect locally stored databases.

Database encryption uses a public-key algorithm. Encryption generates a random encryption key,
encrypts this key with the public key associated with a specific user ID, and appends the resulting key to
the specified database. A user can access an encrypted database only if the user’s private key can decrypt
the appended key. It is a good idea to encrypt local databases if they are stored on a portable computer,
or if you share your computer with other users.

You can also use local encryption to encrypt databases on a server with the server ID. Then, only those
Domino administrators with access to the server ID can read the database.

Note: When a user copies a 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.

Use the local encryption option from the Database Properties box to encrypt databases on a workstation
with a database owner’s user ID, and to encrypt databases on a server with a server ID. To encrypt a
local database after the initial creation of the database or replica, you or the server administrator must
first compact the database.

Encryption levels
When you encrypt a database, you must select one of the following encryption levels: simple, medium, or
strong. The stronger the encryption, the longer it takes to open a database.
v Use simple encryption when security needs are not great. It is enough to deter casual snooping.
v Choose medium encryption (default) to balances security, strength, and fast database access.
v Use strong encryption when security requirements are paramount, and the resulting database access
performance is acceptable.
For more information on encryption, see Administering the Domino System.

To encrypt a database
You must have Manager access in the database ACL to encrypt a database.
1. Select the database icon from your Bookmark pane, and select File - Database - Properties.
2. Click the Database Basics tab, and then click ″Encryption Settings.″
3. Choose ″Locally encrypt this database using,″ and then choose an encryption level:
v Simple
v Medium (default)
v Strong
4. Click ″For″ and then choose a single ID to use to encrypt the database. Remember to choose the ID of
the person who needs access to the database.
5. Compact the database
The encryption does not actually take place until you close and reopen the database.

Chapter 19. Security in an application 393


Note: You can choose an encryption level when you create a new database or database replica. By
default in Notes Release 6 and later, new replicas created locally are encrypted with medium encryption.
You can change the default encryption settings in File - Preferences - User Preferences - Replication.

Encrypting documents and fields


A document is considered to be encrypted if it is created from a form that contains one or more
encrypted fields. Each encrypted field is linked to a key that encrypts the contents of the field. An
encryption key can be secret -- that is, a key that you must send to users in order for them to decrypt a
field -- or public -- that is, a key that is already in a user’s ID file and in the user’s Person document
where it is publicly available.

Public key and secret key encryption


Notes uses public key encryption for electronic mail, and Domino Designer also lets you use public key
encryption for encrypting fields in documents. Every user has a unique public key associated with their
user name and stored in their user ID. Applications reference the keys by the users’ names in a special
field called PublicEncryptionKeys. When a document is saved, all the user names in this field are located
in the Domino Directory or the user’s personal address book, the corresponding keys are retrieved, and
all fields marked with a special property are encrypted with those keys.

Domino Designer also supports secret key encryption that you can use for encrypting fields in
documents. You can create and name secret keys and then distribute the secret keys to users so that they
can decrypt the protected data. Secret keys, like public keys, are stored in a user’s ID. Applications
reference the keys by their names in a special field called SecretEncryptionKeys. When a document is
saved, the keys named in this field are retrieved from the user’s ID file, and all fields marked with a
special property are encrypted with those keys.

CAUTION:
Both public and secret keys are stored in your user ID file. Remember to securely back up your ID
file each time you add a key.

Note: Web users cannot see encrypted fields with a browser. To see the data, Web users must reopen a
document with a Notes Client or ask the sender for a copy that is not encrypted.

Document encryption
If you are planning to use secret encryption keys rather than encrypting with a public key, create the
secret key before you encrypt a document.

You can encrypt documents with keys in several ways:


v Using public keys. You can encrypt documents with public keys on IDs so that only users with those
IDs can read the documents. To do this, you enter one or more names in the Public Encryption keys
field on the Security tab in the Document Properties box.
v Using a form property. Database designers can use a form property to add one or more keys to a form.
Every document created with the form will be encrypted using the encryption keys.
v Using the Database/Document Properties box. Users can use the Database/Document Properties box to
encrypt one or more documents with their own encryption keys stored in their ID files. To use the
properties box to encrypt documents, the form must contain a field that can be encrypted.
v Using the SecretEncryptionKeys field. The SecretEncryptionKeys field can contain either the name of a
key, which is automatically used to encrypt documents, or the field can be blank, allowing users to
assign the encryption key. To encrypt a field with a secret key using either method, users must have it
stored in their ID file.
You can set up forms with text or keyword fields that allow the user to choose whether to encrypt a
document. Designers can also hide the SecretEncryptionKeys field so that users cannot see the names
of the encryption keys.

394 Application Development with Domino Designer 7


Field encryption
A database designer can encrypt fields with secret encryption keys. To decrypt these fields, users must
merge the secret encryption keys into their ID files. If the user does not have the required encryption key,
the encrypted fields appear blank.

Procedural overview: encrypting documents


Before you can encrypt a document, you must create an encryption key and then enable encryption for at
least one field in the document with that key.

A document can be encrypted when it is first saved, or it can be encrypted when saved after an editing
session.
1. (Optional) If you are using a secret encryption key for encryption, start by creating the key. To do this,
see the topic ″Creating a secret encryption key.″
2. Enable encryption for a field.
3. Do one of the following to assign the encryption key to a document:
v Encrypt all documents automatically
v Create a field that generates a list of secret encryption keys
v Allow authors to encrypt documents with their own encryption keys

Enabling encryption for a field


You can enable encryption for more than one field in a form. The field can be any data type.
1. Open the form.
2. Create a field or click an existing field. Then choose Design - Field Properties.
3. Click the Advanced tab.
4. Select ″Security options: Enable encryption for this field.″

If field encryption is enabled in the Client, any field delimiters appear in red. If field encryption is
enabled in Designer, the outline of the field appears in red.

Allowing the author to choose the encryption key


If you don’t 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.

Examples of encrypting documents


The Salary History form in an Employee Information database has a create access list that allows only
members of the Financials group to create Salary History documents. You want to apply security
measures so that only four people in the Financials group can see salary information and can edit Salary
History documents.

There are several ways to accomplish this goal. You can:


v Create a secret encryption key, associate it with the data you want to secure, and distribute it to the
members of the Financials group.
v Identify the four members of the Financials group and use each member’s public key to encrypt the
information.

Using secret key encryption, you create an encryption key called Salary and send it to the four members
of the Financials group. You then enable encryption for the CurrentSalary field and associate the Salary

Chapter 19. Security in an application 395


encryption key with the form. Then, the four people in the Financials group who have the Salary
encryption key can create, read, and edit encrypted salary history documents, including the data in the
CurrentSalary field.

Using public key encryption, you specify the names of the four members in the Public Encryption key list
associated with the CurrentSalary field. Then the people named in the list can create, read, and edit
encrypted Salary History documents, including the data in the CurrentSalary field.

Users who don’t have the Salary encryption key and are not in the Public Encryption key list can read
everything in the Salary History documents, except the data in the CurrentSalary field, but they can’t edit
and save existing encrypted documents.

Creating secret encryption keys


You can create a secret encryption key and then use that key to encrypt fields in a database. Then, only
users who have the secret encryption key can read the fields. Before you distribute the key, you must
merge the secret key into your user ID. Then you can distribute the key to other users, who, in turn,
must merge the secret key into their user IDs.

To create a secret encryption key


1. Choose File - Security - User Security.
2. Click the Notes Data tab, then Documents.
3. Click New Secret Key.
4. Enter a name for the new key.
5. (Optional) Write a comment to explain the key’s use -- for example, the databases to use it with, the
people who have copies of it, and so on.
6. Click OK, then click Done.

To attach a secret encryption key to a document


1. Open the document you are encrypting.
2. Choose File - Document Properties.
3. Click the Security tab.
4. Choose one or more secret encryption keys that you created, or choose the people who can use their
public key to access the document (click the person icon next to the ″Public Encryption key″ field)
under ″Encryption Keys″.
5. Send or close the document.

Considerations
Before you distribute secret keys, consider the following:
v Allow only users who have Manager access in the database ACL to send a key to users. Distribute the
key to other managers of the database in an e-mail that allows them to send the key to other users.
Distribute the key to users in a separate e-mail that prevents them from sending the key to others.
v If you distribute an encryption key to users who have Author access in the database ACL, they can
remove encryption from any documents they create.
v If you distribute the key to users who have Editor or higher access in the database ACL, they can
remove encryption from documents that other users create.

Distributing secret encryption keys


You have two options for distributing secret encryption keys: you can electronically mail them to users,
or you can save the key to a file and give the users the file. The easier distribution method is mail. The
Notes client automatically uses public key encryption to protect your secret key when it is mailed, and it
gives the recipient the ability to add the key to his ID file with a single click. Exporting the key creates a

396 Application Development with Domino Designer 7


KEY file, which you can put on a disk and hand to coworkers, who then have to use the Import Key
button in the User ID dialog box on their own computer to add the key to his user ID.

Consider exporting secret keys to files if you are distributing keys to application users who do not use
Notes mail, because only Notes mail users can receive and merge a key via e-mail. Second, if you don’t
have complete confidence that the recipient’s ID file and password are secure, then you shouldn’t trust
that the mail system is secure enough for something as potentially sensitive as a secret key.

To mail a secret encryption key


When you mail an encryption key, the mail message is, by default, signed and encrypted.
1. Create one or more secret keys and be sure to merge the encryption key with your user ID before
distributing it.
2. From your Bookmark page, select File - Security - User Security.
3. Enter your Notes password.
4. Click Notes Data - Documents.
5. Select the secret encryption key to send under ″Secret Key Name.″
6. Click ″Mail Secret Key.″
7. Enter the names of the people you want to send the secret key to in the To field (click Address to
choose from your Personal Address Book).
8. In the CC field, enter the names of the people who need to know you sent a key, but aren’t getting
one themselves.
9. Click Send.
10. (Optional) Check ″Allow all recipients to forward the key to others by mail or export″ if you want
users to have that capability.
11. Click OK.

To export an encryption key to a file


To export an encryption key to a file that you can distribute on disk:
1. Create one or more secret keys and be sure to merge the encryption key with your user ID before
distributing it.
2. From your Bookmark page, select File - Security - User Security.
3. Enter your Notes password.
4. Click Notes Data - Documents.
5. Select the key to export and click Other Actions - Export Secret Key.
6. (Optional) Do the following to restrict who can use the encryption key:
a. Click ″Restrict Use″ to allow only one person to use this file.
b. Type the hierarchical name of the user.
c. Select ″Allow that person to export the key or forward it to others″ to let the recipient export the
key or mail the key to other users, and then click OK
7. In the Password box, do one of the following:
v Type a password to protect the file. In the confirmation box, retype the password and click OK.
v Click ″No Password.″
8. Type a file name, select a directory in which to store the file, click OK or Save, and then click Done.

Merging secret encryption keys


If a database has a secret encryption key, you must merge the key with your user ID so that you can
distribute the key to users. After users receive the key from you, they merge the encryption key with
their user IDs so that they have access to encrypted fields.

Chapter 19. Security in an application 397


To merge an encryption key received by e-mail
1. Open the mail message containing the attached encryption key.
2. Choose Actions - Accept Encryption.
3. Enter your password, and then click OK.
4. (Optional) Type comments to describe the encryption key -- for example, type the name of the
database and field in which the encryption key is used.
5. Click Accept.

To merge an encryption key received as a file


1. From your Bookmark page, select File - Security - User Security.
2. Enter your Notes password.
3. Click Notes Data - Documents, and then click Other Actions - Import Secret Key.
4. Select the directory, specify the name of file containing the encryption key, and then click OK or
Open.
5. If prompted to do so, enter the password associated with the file, and then click OK.
6. Click Accept.

To create a field that maintains 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 field, the form must already have fields enabled
for encryption.
1. Open the form.
2. Create a field named SecretEncryptionKeys. Define it as a text or list choice field that is editable or
computed.
3. Do one of the following:
v If you’ve created a list choice field, click the Control tab and select ″Enter choices (one per line).″
Write each entry, using a keyword and a synonym that describes the encryption key -- for example,
Encrypt | ConfidentialKey. Use a null value for the ″Don’t encrypt″ option.
v If you’ve created a text field, go to Step 4.
4. Click the Programmer’s pane and choose Formula in the Script area.
5. Do one of the following:
v For a computed field, add a formula that returns the name of the encryption key to use.
v For an editable field, add a default value formula.
6. (Optional) Click the Advanced tab. Select ″Security options: Enable encryption for this field″ so
unauthorized users cannot see the names of encryption keys used in the formulas and keywords.
7. Save and close the form.
8. You or the database manager must distribute secret encryption keys to all users who need them.

If the SecretEncryptionKeys field is empty (null), the document is not encrypted.

Managing encrypted information


As you consider what type of encryption you need in your application, keep the following in mind:

Reading encrypted information


Users can read encrypted information if they have the correct secret encryption key in their Notes User
ID or, in the case of encrypted mail messages, the private key in their Notes User ID. Users without the
correct encryption key can read unencrypted parts of a document, but encrypted fields appear blank. The
user will see a dialog box with the message, ″Portions of this document have been encrypted and are not
intended for you.″
398 Application Development with Domino Designer 7
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 don’t have the correct encryption key in their Notes User ID can’t edit encrypted documents.
They can create new documents but must save them unencrypted by removing the encryption key from
the Document Properties box.

When multiple secret keys are associated with a form or document, users need all of the specified keys to
edit and save encrypted information with the original keys. If they don’t 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 a 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.

When an encrypted database is full-text indexed and the option ″Index encrypted fields″ is enabled, the
encrypted fields are only indexed if there is an encryption key in the ID file capable of decrypting the
field before indexing. One situation where you may want to index encrypted fields is if you create a
full-text index for a database on your own workstation. You probably would not choose this option on a
full-text indexed database on a server.

Note: Data in the full-text index is stored unencrypted.

Field encryption and views


As you plan your design, keep in mind that encrypted fields do not display in views. This is a deliberate
restriction to maintain security and to avoid the performance degradation that would result from having
to decrypt data as the view sorts.

To encrypt all documents automatically


You can set up a form to encrypt all encryptable fields automatically. Then, whenever someone saves a
new document composed with that form, all the encryptable fields in that document are encrypted using
the key(s) you assigned, unless the author or editor changes the encryption keys associated with the
document or disables encryption.

Documents created before you add the encryption keys remain unencrypted; however, you can manually
encrypt them. For the details of manually encrypting data in a document, see Notes Client Help.
1. Open a form.
2. Enable encryption for one or more of the form’s fields.
3. Choose Design - Form Properties.
4. Click the Security tab.
5. 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.
6. Save and close the form.

Note: If you use secret rather than public encryption keys, you must distribute the keys to all users who
need them.

Chapter 19. Security in an application 399


Using electronic signatures in Notes applications
For extra security in Notes applications, you can design forms that will attach electronic signatures to
documents. Electronic signatures assure a reader that the writer’s identity is genuine and that information
has not changed since the writer mailed or saved the document.

Note: Signatures are valid only in Notes applications; they are not supported on the Web.

How designers create a form


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 controlled-access sections.

You can enable signing of one or more fields on a form. If the field is in a controlled-access section, the
signature applies only to the section and is generated when the document is saved. If the field is not in a
controlled-access section, the signature is generated only when the document is mailed.

To generate multiple signatures on a form, create multiple signature-enabled fields in separate


controlled-access sections.

How Designer stores and verifies electronic signatures


Designer combines the data in a signature-enabled field with the private key from the sender’s User ID to
create a unique electronic signature. Designer stores the signature, along with the public key and the list
of certificates from the sender’s ID, in the document.

Storing signatures in documents


Designer stores signatures in mailed documents with the document.

If a user with Editor access in the database ACL changes a field in a document, Notes replaces the
existing signature with the signature of the editor when the document is mailed. Notes cannot save more
than one mail-time signature for a document.

If the document contains several signature-enabled fields, Designer uses data from each signature-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


Instead of signing an entire document, you can sign a section within a document and store an electronic
signature with the section.
v For documents with one sign-enabled, controlled-access section, Designer stores the signature with the
section.
If a user with Editor access in the database ACL changes a sign-enabled section, Designer replaces the
existing signature with the editor’s signature when the document is resaved.
If there are several sign-enabled fields in the section, Designer uses data from each sign-enabled field
in the section to generate a signature. After saving, a change to a field in the document causes
verification to fail when a reader opens the document.
v For documents with several sign-enabled, controlled-access sections, Designer stores signatures within
each section, so it is possible to maintain multiple signatures for a document.
If a user with editor access changes one or more sign-enabled sections, Designer replaces all original
section signatures with the newer signature when resaving the document. Designer preserves the
existing signatures for sections for which the user has no access.
If there are several sign-enabled fields within a section, data from all the sign-enabled fields in that
section is used to generate a signature. A change in any fields in the document after saving causes
verification to fail when a reader opens the document.

400 Application Development with Domino Designer 7


Example of signature verification
1. Mary mails or saves a sign-enabled document. Notes uses the private key from Mary’s User ID and
the sign-enabled field data to create a unique signature. Designer also stores Mary’s public key and
certificates with the document.
2. David opens the signed document to read it.
3. Notes checks to see if the document was signed. If it was, Designer checks the signature against the
data to see if it matches.
4. Notes checks the certificates that came from Mary’s ID against David’s ID to see if they share a
common certifier or cross-certificate in the ID.
5. One of the following occurs:
v If the signature and data are verified, Notes displays a message indicating who signed it.
v If the data has been modified, Notes displays a message indicating that the document has been
changed or corrupted since Mary saved it. David should not assume that the content of the
document is what Mary created.
v If the signature can’t be verified or David and Mary don’t share a common certificate, Notes
displays a message that the signature can’t be verified. David should not assume that Mary created
the document.
For more information on certification, see Administering the Domino System.

Attaching signatures to documents


When you design a form for an electronic signature, you can design it so that either the user is prompted
to sign the document when mailing it or the document is automatically signed.

To enable signing:
1. Create a form with a SendTo field or, alternatively, create a LotusScript program that uses the Send
method of the NotesDocument class with a recipient’s argument.
2. Create at least one sign-enabled field of field type COMPUTED. To sign-enable a field, assign the
property ″Sign if mailed or saved in section″ in the Advanced tab of the Field Properties box.
3. Enable the form for mailing in one of the following ways:
v Use a Send Document form action
v Enable the form property ″On Close: Present mail send dialog″
v Create a MailOptions field with the value 1
v Use an @MailSend formula, or a program created with IBM LotusScript 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.

To attach signatures to controlled-access sections


If you set up a controlled-access section for signing, Domino attaches an electronic signature when the
document containing the controlled-access section is saved.

To attach a signature to a document when it is saved:


1. Create a form with a controlled-access section.
2. In the controlled-access section, create at least one sign-enabled field. To sign-enable a form, assign the
property ″Sign if mailed or saved in section″ in the Advanced tab of the Field Properties box.
3. Save and close the form.

Chapter 19. Security in an application 401


402 Application Development with Domino Designer 7
Chapter 20. Completing an application and managing design
changes
As you prepare to deploy an application, consider these finishing touches:
v Creating an icon for the application.
v Creating database Help using the standard ″About this Database″ and ″Using this Database″ pages, or
with a designated home page that describes the application or site.
v Providing context-sensitive Help for an application
v Customizing SmartIcons sets for a Notes application to give users one-click buttons for frequent tasks

Then, before handing over the application to the database manager:


v Test the design
v Make a master design copy to manage future design changes
For more information on putting a database into production, see the chapter ″Deploying an
application.″

Creating a database icon for a Notes application


A database icon helps users identify the database quickly on their Bookmark pane. An icon visually
represents the purpose of the database. For example, a discussion database where users ask questions
about new products could include an icon with a question mark.

You can create a database icon by copying an icon from another database and pasting it in, by pasting a
bitmap from a graphics application, or by creating an icon in Designer.

To paste an icon into a database


1. Copy an icon from another database or copy a graphic from a graphics application to the Clipboard.
If you are copying a bitmap, reduce the bitmap size to a 1/2-inch square (32 x 32 pixels). You cannot
resize it in Designer, and Designer truncates larger bitmaps.
2. If you have not already done so, copy the bitmap to the Clipboard.
3. In Designer, open the database in which you want to paste the icon.
4. In the Design pane, click Other - Database Resources.
5. Double-click Icon to start the Design Icon editor.
6. Click Paste.
7. Edit the icon in the Design Icon editor.

To create a new icon


You must have a mouse to create a new icon.
1. Open a database in Designer.
2. In the Design pane, click Other - Database Resources.
3. Double-click Icon to start the Design Icon editor.
4. Click a color and then click a square to fill it with the chosen color.
5. Continue filling in squares until the icon is complete.
6. Click OK to save the icon.

403
Note: Icon changes replicate and can be affected by replace or refresh design procedures. The icon design
will refresh or replace if you disable ″Prohibit design refresh or replace to modify″ on the Design tab of
the Design Document Properties box (To get this Properties box, select Icon in the Work pane and then
select File - Design Properties).

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


v ″About This Database″ and ″Using This Database″ documents describe the database purpose. You can
also create a page that provides this type of information.
v The document preview pane lets users scan through documents quickly to get a sense of what’s in the
database.
v Database launch settings allow you to display the most useful starting point for users. This might be
the ″About This Database″ page or it might be the home page for the application.
v Context-sensitive Help in applications provides task-specific information as users need it. They can
access the information with a Help button or the F1 key in a Notes application or with a Help button
in a Web application.
v Field Help describes the purpose and use of individual fields.
v A Help view organizes and displays Help documents.
v A separate Help database can be set to stay on top of other windows in your application while users
work.

Creating ″Using Database″ and ″About Database″ documents


Every database should include a ″Using Database″ and an ″About Database″ document to explain the
database to users.

The ″About Database″ document


Use an ″About Database″ document to describe the purpose of a database. You can specify that the About
document opens automatically when a user opens the database. To display this document, choose Help -
About This Database.

The About document should include:


v The purpose of the database.
v The intended audience.
v The name and telephone number of the database manager.
v The date the database was implemented.
v Guidelines for its use.
v Network requirements if users must be connected to the network to perform certain tasks -- for
example, if the application uses lookups that require a network connection.
The About document can contain rich text, so you can also use document, view, and database links,
buttons, attachments, graphics, or multimedia files.

The ″Using Database″ document


Create a ″Using Database″ document to provide users with instructions on using various forms, views,
and navigators in the database. To display this document, users choose Help – Using This Database.

404 Application Development with Domino Designer 7


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:


v A brief overview of the application.
v The purpose of each view and its organizations.
v The purpose of each form and how to fill it out.
v The purpose of each agent, when to run it, and the anticipated results.
v The overall work process being automated, if appropriate, including what happens at each stage. When
users fill out documents, they should understand what happens after the documents are saved, and
what other users are expected to do.

To create a document
1. In Designer, open the database you’re designing.
2. In the Design pane, click Other - Database Resources.
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 Database″ document


1. Choose File - Database - Properties and click the Launch tab.
2. Do any of the following:
v Select ″On Database Open: Open About database document″ so that this document always opens
first.
v Select ″Show About database document if modified″ so that if you edit the document, it opens to
users again.
v If you want each user to see the About document the first time they open the database, select
″Show About database document when database is opened for first time.″
v Select ″On Web Open: Open About database document.″

You can use this document as a springboard to a file in another database or another product’s file. To do
so, use the Database Properties Launch options for ″Launch first attachment in About database
document″ or ″Launch first doclink in About database document.″

Creating context-sensitive Help for an application


You can make an application’s Help documents or pages context-sensitive so that users can open them by
pressing a key, such as F1, or by clicking a Help button. You can associate a Help document or page with
each page, form, subform, view, and folder in an application.

When you provide Help for an element, your formula overrides whatever context-sensitive Help already
exists for that element. This feature is not intended for context-sensitive Help on dialog boxes or menu
items.

To create context-sensitive Help for a Notes application, you write a formula for the HelpRequest event
for a page, form, subform, view, or folder. You can use the formula language command
@Command([OpenHelpDocument]) to specify which Help document to open when a user requests Help
while an element is active. You can also use @helpCommand([OpenPage]) to open a page instead of a
document.

Chapter 20. Completing an application and managing design changes 405


The HelpRequest event is not available for applications over Web servers; however, you can create a
button for an element and program the button using a formula with @Command([OpenHelpDocument])
or @Command([OpenPage]). A user clicks the Help button to see the associated Help document or page.

Because the HelpRequest event accepts a formula, you can use the formula language in other ways to
provide Help. For example, you can use an @If formula with @IsDocBeingEdited to provide different
Help for a form depending on whether a document is being read or edited, or depending on other
conditions specific to your application. You can present a dialog box to allow users to select among
several Help documents or pages. You can place Help text directly onto a form or page, set the text with
a hide-when formula, and use a formula on the HelpRequest event to reveal the text (by changing the
value of a document field) when a user requests Help.

Note: To open documents in response to Help requests, there must be a view containing those
documents sorted by a key field that you can use as parameters for @Command([OpenHelpDocument]).
You can use @Command([OpenPage]) without requiring a specific view or key field.

For syntax and usage information on using @Command([OpenHelpDocument]) or


@Command([OpenPage]) in a formula, see the Domino Designer Programming Guide.

Writing Help for fields


Field Help is optional, but it can Help users fill out documents without assistance. A field label that
appears next to the field describes the field’s 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, a one–line text
prompt appears at the bottom of the window.

If you cannot fit all the information into a Help description or if the field isn’t editable, but you want to
explain its use, use pop-up text in the field label to place Help information directly on the form. You can
also write a field hint, text that helps the user determine what to enter or select in the field. The text
disappears when the user moves the cursor into the field.

Tips for writing Help for fields


Start the Help description with ″Required:″ if the user must fill in the field.

You can use 70 characters, including letters, numbers, spaces, and punctuation. If your application will be
translated to another language, use no more than 55 characters to allow the translators a few extra
characters.

To write field Help


1. Open the form in Designer.
2. Double-click the field.
3. In the Field Properties box, click the Advanced tab.
4. Enter your help text in the Help Description setting.
5. Save and close the form.

To write pop-up text for a field


1. Open the form or subform in Designer.
2. Highlight the field label -- that is, static text that the user sees, not the rectangular field definition.
3. Choose Create - Hotspot - Text Pop-up.
4. In the Hotspot Properties box, write the pop-up text and click the green check mark.
5. Save and close the form or subform.

406 Application Development with Domino Designer 7


To write a field hint
A field hint lets you enter descriptive text that initially helps the user know what to enter or select in the
field. This text disappears when the user moves the cursor into the field.
1. Open the form in Designer.
2. Double-click the field.
3. Click the Advanced tab.
4. In the Field Hint box, type the text you want to appear.

Examples
For a text field named Supervisor:
Enter the name of the person to whom you report.

For a keywords field that presents check boxes:


Select as many options as apply.

For a required Subject field:


Required: You must add a brief description.

Creating and displaying more detailed application Help


In a complex application, an ″About Database″ document and a ″Using Database″ might not provide
enough documentation. To provide detailed documentation for an application, design a Help form as part
of the database and display documents created with that form in a Help view. The following steps
describe one way to achieve this.

To create a Help form


1. Create a new form called ″Help″ and create fields for Help content.
2. Choose Design - Form Properties.
In the Name box, type a name and alias for the form (for example, Main Topic | Interview). For more
information on naming a form, press F1 on the Form Info tab.
3. Select ″Event: Window Title″ and enter ″Help″ as the window title text in the formula window below.
4. Save and close the form.
5. Choose Create - Help for each Help document.
6. Click the form you’re designing and choose Design - Form Properties.
7. Deselect ″Include in Menu.″
8. Click the form, and then save it.
9. Create a view that displays the Help documents.

Note: You can also create a separate Help database and open its documents from your application using
@Command(OpenHelpDocument). To open documents from a Help database in a window that users can
set to stay on top of other windows as they work, choose File - Database - Properties - Design for your
database. Then, turn on ″List in Database Catalog″ and enter the category ″NotesHelp.″

Specifying a home page in the Web site document


To make a design element the site home page, open the Web site document. Specify a URL that includes
the design element in the ″Home URL″ field.

Chapter 20. Completing an application and managing design changes 407


To open the Web site document from the Domino Administrator, click the Configuration tab. In the
Internet Sites view, open the Web Site document for the Web Site you want to modify. Click
Configuration and edit the Home URL field. For more information, contact your server administrator.

If you set an ″About This Database document,″ a navigator, a page, or another document to launch
automatically when a user opens the database, the Home URL need only open the database to launch the
design element. The syntax is:

/databasename.nsf

This URL opens the Our Home database and displays whatever is selected in the ″On Web Open″ launch
setting:
/ourhome.nsf

To open a 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

Restricting design changes


Once an application is complete and available, you decide how to protect the design from changes. An
application can have a totally open design, where users can update forms and views and pass along
design changes. Or 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 related information, see the topic ″Hiding the design of an application″ later in this chapter.

Checking the application design before release


After you complete the design, test the application and correct problems before you release it.
v Check the design of forms, fields, views, outlines, pages, and all other design elements
v Check the ACL of the database
v Check the database properties, including the launch option
v Check the About and Using documents for accuracy and completeness
v Verify that agents and actions work as designed
v If the application is Web accessible, check that the application runs from a Web browser and all
components display as expected
v Save the design template
v Distribute the application for a final review
v Pilot-test the application
v Make design changes before release
v Request application sign-off

408 Application Development with Domino Designer 7


For more information on putting a database into production, see the topic ″Deploying an application″
later in this chapter.

Checking form design


For each form you want to check, create two or three documents and enter a variety of information into
the fields. Then use this check list to verify that the form is working as intended.
v 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.″
v 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.
v 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.
v 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.
v 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.
v 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.
v Do the forms include Names fields where appropriate for tracking document authors and editors?
If not, add a Names field to the form.
v Has a read-access list been defined for the form?
If one is needed, define a read access list by assigning names to a Read access control list on the
Security tab of the Form Properties box.
v Has a create access list been defined for the form?
If one is needed, define a create access list by assigning names to a Compose access control list on the
Security tab in the Form Properties box.

Checking field design


v Are fields (including keywords fields) showing the correct information when first displayed?
If not, check the default value formula.
v 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. Check that ending punctuation is
consistent for each. Note that you can also add field hints for each field.
v Can users enter information in editable fields?
If not, check the field definition. You may have selected the Computed option when defining the field.
v Are editable fields formatted correctly once the document is saved?
If not, check the input translation formula and the format for the field.
v Are editable fields accepting invalid data or not accepting valid data?
If so, check the input validation formula.
v Are computed fields computing correctly? Are they returning values of the appropriate data type?

Chapter 20. Completing an application and managing design changes 409


If not, check the field formula. The formula may need to include some data type conversion such as
@TextToNumber.
v Do inherited fields inherit their data correctly?
If not, check the field’s default value formula.
v 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.
v In time–date fields, is the time displaying correctly?
If not, make sure you selected the appropriate time zone option in the Field Properties box.
v Are fields aligned properly with a variety of window sizes and on different monitors?
If not, check the tab settings for the form.
v 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.
v Do fields have field hints?
If not, you might want to consider adding them.
For information on writing field help and field hints, see the topic ″Writing Help for fields″ earlier in
this chapter.

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.
v 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.″
v 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,
or choose a sort value on the Sorting tab of the Column Properties box, or create a date column in an
existing view that the user can sort in both ascending and descending directions.
v 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.
v 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.
v 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.
v 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.
v 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.
v If the view uses categories, do the categories appear correctly?
If not, create a sorted, categorized column and use the name of the appropriate keywords field as its
formula.

410 Application Development with Domino Designer 7


v If the view uses a form formula, do selected documents use the correct form?
If not, verify that the view uses a form formula.
v 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.
v If needed, does the view have a read access list?
To create a read access list, select the Security tab in the View Properties box.
v Are columns displaying in the correct color and highlighting?
v If documents can be expanded, are twisties displayed?

Checking columns
v Is the information in each column correct?
If not, check the formulas in the column definitions.
v 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.
v 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.
v If you are using a date format in a column, have you accommodated 4-digit years so that you avoid
problems with the year 2000 and beyond?
v 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.
v 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).
v 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.
v Are columns displaying the correct color and highlighting?
If not, select ″Use value as color″ on the Info tab of the Column Properties box.
v If documents can be expanded, are twisties displaying?
If not, select ″Show twistie when row is expandable″ in the Column Properties box.

Making a design copy of a completed application


Before delivering the database to the database manager for general release, make a local template copy.
You can make future design changes to the template and then transfer them to the server database.
1. Select the database and choose File – Database – New Copy.
2. Select Local.
3. Enter a title for the template.
4. Press TAB and change the file name to include the NTF extension reserved for templates. 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 doesn’t exist, Notes creates it for you.
5. Select ″Database design only″ in the Copy section of the dialog box.
6. Deselect ″Access Control List.″

Chapter 20. Completing an application and managing design changes 411


7. (Optional) Click Encryption to encrypt the database and protect its contents from being accessed at
the operating system level. Then click OK.
8. Choose File – Database – Access Control to define an appropriate access control list for the template.
The following access levels are recommended for the access control list of a template used for design
maintenance:

Default Reader
Local Domain Servers Reader
Other Domain Servers No Access
Your User Name Manager
Database Manager Manager
[Anonymous] No Access -- or whatever the actual database should have
[Default] No Access -- or whatever the actual database should have
[LocalDomainServers] Manager -- or whatever the actual database should have
[OtherDomainServers] No Access -- or whatever the actual database should have

Note: The items within the square brackets are needed only if the template is going to be used for
creating new databases. The brackets are required for these entries.
For more information on putting a database into production, see the chapter ″Deploying an
application.″

Pilot testing an application


Once your application has been reviewed, pilot test it with a few users. Make sure that the application
works correctly and that all instructions are clear. Because the application users have a different point of
view, they often uncover problems missed during the review cycle.

Only the people specifically assigned to pilot test the application should have access to it. The default
access should be ″No Access.″ Then you can assign specific access levels and privileges to make sure that
certain users can access only what they should. Make sure you retain Manager access, so you can make
changes to the access control list during the test period and solicit comments from the testers.

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. Create an ″About 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. Create a Comment form to make it easy for testers to give you feedback. Include the comment form
in at least one view. (Make sure that the comment form is marked in the form design to be included
on the Create menu, or that a button or action is available to the user to compose the form.)
4. Choose File - Database - Access Control to add testers to the access control list. Be sure to retain
Manager access for yourself.
5. Ask your Notes administrator for Write access to a server for the pilot test. Also, 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.
For more information on copying a new database to a server, see the topic Copying a new database to
a server in the chapter ″Deploying an application.″

412 Application Development with Domino Designer 7


7. If the database will use replication later on, either to mobile laptops or between servers, confirm that
the replication formulas are working and that servers can handle the volume of replication. For
example, an annual review system places a demand on the server during the review writing time, but
not at other times.
If users will be replicating, then the pilot needs to confirm that replication instructions are appropriate
for the levels of user expertise. While the initial part of the pilot test may be limited to a single server,
if the intended implementation involves multiple servers, then the pilot test needs to address some of
these issues as well.
For more information on replication, see Administering the Domino System.
8. Keep track of questions that people ask about the function or use of the database. Their questions
may include the ″Using Database″ document or to the design of the database.

Renaming a database
If you want to change the title of a database, you can edit the title. The database title is the name that
appears as the default bookmark name and the name that appears when you choose File - Database -
Open. Note that a database name or title is not the same as the database file name. The file name
associated with a database is permanent. The only way to change the file name is to make a copy or a
replica of the database and give the new database a different file name.
1. Open the database.
2. Choose File - Database - Properties.
3. Enter a new database title.

Renaming design elements


For most design elements, you can follow these steps to rename the design element.
1. Open a database in Designer.
2. In the Design pane, click the type of design element you’re working on.
3. Select the name of the design element in the Work pane.
4. Do one of the following:
v For a script library, choose Edit - Properties.
v For many design elements, such as views, agents, or actions, you can double-click the specific name
of the design element to display its properties box..
v For other design elements, such as forms or pages, you must double-click the name of the form or
page and then choose Design - <design element> Properties.
5. Edit the name of the design element.
6. Save and close the design element.

Design synopsis
The Design Synopsis dialog box lets you generate a detailed report on a particular database. The report
lets you:
v Gather information on a database
v Select the design elements you want in your report
v Filter the contents of the report so that you do not automatically get a lengthy report
v Display the report on the screen or have it written to a specified database

To create a design synopsis


1. Open the database for which you want a report.

Chapter 20. Completing an application and managing design changes 413


2. Choose File - Database - Design Synopsis or select Synopsis in the Design pane. The Design Synopsis
dialog box.
3. Click the Design Elements tab and do the following:
v Select design elements one at a time from the list. If you want every element of every design to
appear, select All from the list.
v Choose the specific elements that appear for each of the design elements. For example, if you
selected Forms in the list, all the forms in the database are listed. Select the ones you want in your
report. For example, if you have created a hide-when formula on a page and want to see the
hide-when formula in the design synopsis, select that page in the list.
v The Add button lets you add specific elements one at a time to your report. The ″Add All″ button
adds all the elements of a particular design element (for example, all the forms). Your selections
appear on the right. If you want to add every element of every design element, choose All from the
design list and then click ″Add All.″
4. Click the Database Information tab. Then, check the appropriate boxes to include information in your
report on the following topics:
v General information -- gives information such as the database title, location, and categories.
v Space usage -- calculates information such as the file size, number of documents, and space used by
the database.
v Replication -- gives information on the replication settings for the database.
v Access list -- generates a list of users, groups, and servers in the ACL and specifies assigned access
levels and access roles for each.
5. Click the Content tab. Then do the following:
v Check the details you want on each design element. For example, for Forms, you can check Alias
and ″Last Modification.″ Those details appear for each selected form in the database.
v Check the appropriate boxes so that your report includes information on subcomponents (such as
formulas), LotusScript code, Java code, HTML code, or JavaScript code.
To generate customized reports, use the DXL Transformer utility. It applies XSL stylesheets to the DXL
representation of one or more design elements. This means that raw XML-based data which describes
a form can be converted into a rich HTML document, allowing full control over content and format.
6. Click the Output tab. Then do the following:
v Choose blank lines or page breaks as report separators.
v (Optional) Check the Write Output to Database box if you want to write the report to a database. If
you check this box, a new dialog box appears letting you specify the database where you want the
output written.
7. Click OK to generate the report.

Unless you chose to have the report written to a database, the generated report is displayed in a new
window. You can print it or save it in a file.

Updating documents after redesigning a form


When you redesign a form, be aware of the effect on existing documents. Some form changes, such as
formatting changes, automatically display when users open an existing document. Other changes, such as
adding a new field, do not display in existing documents until you update the documents manually or
by running an agent. If the database replicates, redesign the form on only one database and let the
changes replicate to other replicas.

Form changes that don’t require updates to existing documents


As long as the form doesn’t have the ″Store form in documents″ property set, changes in the following
form elements display automatically in existing documents. When users open a document, they see the
changed format.

414 Application Development with Domino Designer 7


v Computed field formulas
v Static text on the forms
v Pop-ups
v Text properties and formats
v Form actions and buttons
v Graphics
v Form names if you leave the original name as a synonym to the right of the vertical bar (|) symbol.

Form changes that require updates to existing documents


v New fields
v Field data types
v Field names
v Deleted fields
v Form names if you don’t leave the original name as a synonym.
v Form types -- for example, from Main to Response
v Forms with the property ″Store form in document″

Checking field values in a document


Open the Document Properties box to see if a document contains a particular field or field value, or to
troubleshoot a field that is not calculating its value correctly. A null value (″″) indicates that the field is
empty.

A document always contains fields you design as well as fields Domino automatically generates. Most
fields generated by Domino start with a dollar sign ($). Some Domino-generated fields include:
v $File -- shows an entry for each attachment in the document.
v $Links -- shows an entry for each link in the document.
v $Readers -- lists authorized readers if the document contains a read access list.
v $Revisions -- lists the date and time of each editing session since the first time the document was
saved.
v $Title, $Info, $WindowTitle, $Body, and $Actions -- are associated with a form that is stored in the
document.
v $UpdatedBy -- lists the document authors and editors. Anonymous forms don’t have this field.
v Form -- indicates the name of the form used to create the document or the name of the form most
recently used to save the document. Use the form in views to select documents created with the form.
v PostedDate -- indicates that a document has been mailed and shows the time and date it was mailed.

To check field values in a document:


1. Select the document in a view.
2. Choose File - Document Properties.
3. Click the Fields tab.
4. Click a field name in the left column to display the field.

Using agents to update documents affected by form changes


To update multiple documents affected by form changes, use an agent. To do so, it is best to create
private agents and run them manually.

Chapter 20. Completing an application and managing design changes 415


To edit and resave documents
To save the step of editing and resaving documents manually, create an agent that uses the formula:
@Command([ToolsRefreshAllDocs])

To add a field
If you create a new field, create an agent that inserts the new field into existing documents using the
formula:
FIELD New field name := value;

where New field name is the name of the field and value is the value you want the field in these
documents to have. The value can be the field default value; a formula that calculates the value; or a null
value (″″) that inserts the field into the documents, but doesn’t give them any initial value.

To remove field data from all documents


If you delete a field, existing documents continue to store the obsolete field and its values. This
unnecessary storage can affect disk space. To remove the obsolete field, create an agent that uses the
formula:
FIELD Field name := @DeleteField;

After you run the agent, compact the database to reduce the actual file size of the database.

To rename a field
If you rename a field, existing documents continue to refer to the old field name. To update documents to
refer to the new name, create an agent that uses the formula:
FIELD New field name := Old field name;
FIELD Old field name := @DeleteField;

where New field name is the new name for the field, and Old field name is the original name for the field.

To reassign documents to another form


If users attempt to open documents created with a deleted form, they see a message indicating that the
form cannot be found. To prevent users from seeing this message, use these agent options to reassign
existing documents to another form.
1. Click on Agents in the Design pane and then double-click an agent listed in the Work pane. The
Agent Properties box appears.
2. Next to Trigger, check ″On schedule.″
3. Next to Target, select ″All documents in database″ and click Add Search.
4. In the Programmer’s pane, click Formula and enter:
FIELD Form := ″Reassigned form name″;
where Reassigned form name is the name of the form that the documents should use.

To remove the stored form from documents


In designing mail-enabled applications in which users need to see a document and don’t have the
original form stored in their mail databases, select the form property ″Store form in documents.″ This
form property is permanently attached to all documents created with the form. To remove the stored
form, remove all internal fields connected with the form by creating an agent that uses the formula:
SELECT $TITLE="Old form name";
FIELD $TITLE:=@DeleteField;
FIELD $INFO:=@DeleteField;
FIELD $WINDOWTITLE:=@DeleteField;

416 Application Development with Domino Designer 7


FIELD $BODY:=@DeleteField;
FIELD $ACTIONS:=@DeleteField;

This formula removes all internal fields attached to the documents where Old form name is the name of
the form used to create the documents.

To specify a form to display documents


You can display a document with a form that you specify rather than a stored form. To do so, create an
agent that uses the following formula:
FIELD FORM:="New Form name";

This line creates a FORM field where New Form name is the form that will display the documents.

To recover additional space


You can delete items with the suffix ″_StoredForm″ and ″_StoredSubFormN″ where N is the number of
subforms used by the form. (If the form does not use subforms, then ″_StoredSubFormN″ does not exist.)
Determine the number of subforms and then delete each of them by running a LotusScript or Java agent.
You can recover additional space by deleting the following items: $StoredFormCRC, $FormRepID, and
$Subform_RepIDS.

After you run the agent, compact the database to reduce the actual file size of the database.

Changing database and design properties


The Properties boxes for a database and its design elements include styles, options, and other settings
that affect how the database looks to users. To change these properties, you need Designer access or
higher in the database access control list.

To change a database’s properties


1. Open or select the database.
2. Choose File - Database Properties.
3. Change the properties on any of the tabbed pages.

To change a design element’s properties


1. Open the database.
2. In the Design pane, click the type of design element you’re working on.
3. Select the name of the design element in the Work pane.
4. Do one of the following to open the Properties box for the selected design element.
v For a script library, choose Edit - Properties.
v For many design elements, such as views, agents, or actions, you can double-click the specific name
of the design element to display its properties box..
v For other design elements, such as forms or pages, you must double-click the name of the form or
page and then choose Design - <design element> Properties.
5. Change the properties on any of the tabbed pages.

Chapter 20. Completing an application and managing design changes 417


Setting database launch properties
You can set database properties that control what a user sees when the database opens. For example, you
might want all users to start from an application home page or a registration page. Or you might display
a main navigator that leads users to different pieces of the application. You can specify one option for an
application when it runs on a Notes client and another option for the application when it runs on the
Web.

When the database opens on the Notes client, you can display:
v A frameset you specify
v A navigator you specify
v A navigator in its own window
v The ″About Database″ document for the database
v The first attachment in the ″About Database″ document
v The first doclink in the ″About Database″ document - Adding a link here gives users access to
information in another application from a Designer application. For example, to collect spreadsheet
data for use in the application, launch a link to a spreadsheet application so users immediately see the
spreadsheet when they open the database. Data entered in the spreadsheet can be used to populate
fields in the application. If you choose to launch a page, you will need to specify the page in the
Properties box. Designer gives you a drop-down list of the pages that are available to choose from.
they open the database. Data entered in the spreadsheet can be used to populate fields in the
application.

When the database opens on a Web browser, you can display:


v Using the Notes launch option
v The ″About Database″ document
v A frameset you specify
v A page you specify - in the Database Properties box, Designer gives you a list of the pages that are
available to choose from.
v A navigator in its own window
v The first doclink in the ″About Database″ document
v A doclink you specify
v The first document in a view

To set the database launch property


1. Select or open the database and choose File - Database - Properties.
2. Click the Launch tab.
3. Choose what to display for a Notes client and for a Web client
4. (Optional) Choose whether to restore the database as the last user viewed it
5. (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.

If you choose to launch a doclink


1. Copy the doclink on to the clipboard.
2. Open the Database Properties box.
3. On the Launch tab, choose - On Web open launch designated doclink.
4. Click Paste doclink.

418 Application Development with Domino Designer 7


To launch a Page from the Notes client
1. On the Launch tab of the Database Properties box, choose On Database Open - Open designated
Navigator.
2. Select Type of Navigator: Page.
3. Enter or select the name of the Page.

Displaying a document preview automatically


You can automatically display a preview pane that shows the contents of the highlighted document in a
database view before the user opens the document. This gives users a sense of what is in a database
without having to open and close each document. If you do not display the preview pane automatically,
users choose View - Document Preview to access it.
1. Select or open the database you are designing and choose File - Database - Properties.
2. Click the Launch tab.
3. Click ″Preview Pane Default.″ Note that this option is not available if you launch a frameset from the
Notes client.
4. Choose a location for the document preview pane to display.
5. Check ″Maximize document preview on database open″ to display the preview pane automatically.
Note that this option is not available when setting launch properties from the Notes client.

Templates
A template is a skeleton that contains design elements, but no documents. When you use a template to
create a database, the template’s design elements are copied to the database created from that template.
You can use the Designer templates as is or customize them. Or, you can create a template by creating a
database with the NTF file extension and the ″Database is a template″ property. This property enables the
master template to distribute design changes automatically to databases created from it. Databases that
inherit their designs from master templates receive the latest changes through a nightly server task.

Note: If, for some reason, you do not want a database to inherit designs automatically via the nightly
server task, you have two options: Do not put the template on a server that runs the nightly update task
or do not set the ″Database is a template″ property. You can then distribute changes to the database
design by using the Replace Design command, specifying the server where the template is located and
selecting the template. Make sure to set the database properties so that the database does not
automatically inherit the design via the nightly server task.

To convert a database to a template


1. Open the database you want to be a template and choose File - Database - Properties.
2. Click the Design tab.
3. Select ″Database is a master template.″
4. Enter a template name.
5. (Optional) Select ″List as advanced template in ’New Database’ dialog″ to hide the template. Users
who select ″Show all templates″ in the New Database dialog box can still view the template.
6. (Optional) Select ″Copy profile documents with design″ to propagate to databases created from the
template any profile documents within the template.
7. (Optional) Select ″Single Copy Template″ to designate the template as the repository for all of the
design notes. Databases that inherit from this template will store references to the design notes rather
than the notes themselves.

Chapter 20. Completing an application and managing design changes 419


Naming conventions
v You can use letters, numbers, and underscores in the name. Choose a name that indicates the
application type or design elements represented in the template. For example, StdR6Disc represents a
standard Notes template containing the design for a Lotus Domino Designer 6 Discussion database.
v The master template name, the title, and the categories assigned to the database cannot add up to more
than 99 characters.

Creating templates
Using a template, you can establish design standards for use throughout your company. In large
companies, a central development group usually designs and manages templates to provide consistent
designs and speed up distribution of new databases. Use a template to standardize similar types of
applications -- for example, all discussion databases -- or to store individual design elements, such as
fields, forms, views, folders, navigators, and agents that you can use in a variety of applications.

To customize a Designer template, choose File - Database - New Copy to copy the original template and
inherit the original design. Give it a different file name in the Copy Database dialog box to prevent future
releases from writing over your customized template.

Here’s a list of changes you might make when you customize a Designer template:
v Leave the original Designer template properties alone so that existing databases that inherit their
design will continue to be synchronized with the template.
v Change the newly copied template file name in the Copy Database dialog box (change File - Database -
New Copy) to a name that indicates its intended use.
v Change the newly copied template name (choose File - Database - Properties) to a name that indicates
the new template’s purpose.
v If existing databases that inherited the original Designer template design need to inherit the design
from the newly created template, edit the database properties of those databases to reflect the name of
the newly copied template.

Advantages of standardizing with templates


v Anyone can quickly and easily create a new database
Users need to know only one menu selection: choose File - Database - New. They never have to modify
the design and don’t need to know anything about database design.
v Developers and experienced users can save design time
Forms, views, and agents copied from a template require no additional design work or updates. Using
a pre-designed form or view that contains complex formulas or a large keywords list reduces the
chance of design errors and requires less testing time before a database is rolled out.
v Databases appear consistent to users
View, forms, and fields associated with a template use the same names in all databases. This allows
users to apply their knowledge of one database to many databases.

Design considerations
v The template usually does not control the database icon, the About This Database document, and the
Using This Database document. If you want an icon, About document, or Using document to inherit all
design changes, go into Designer, choose Other - Database Resources, select the icon or document, and
make change in the Properties box so that changes are inherited from the template. The default is not
inherited. You can also change these design elements by manually copying and pasting the redesigned
elements into databases linked to the template.
v Do not create private agents or folders in templates; their changes can’t be distributed automatically. If
a private agent or folder exists in a template, you receive error messages when the design is

420 Application Development with Domino Designer 7


refreshed/replaced. In the case of a shared/private-on-first-use folder: if the folder in the template has
been opened or tested, a private folder exists and that folder generates errors when you try to refresh a
design.
v Databases that inherit their design from a template you create do not contain the ACL entries
LocalDomainServers and OtherDomainServers. You must add these entries to the template with
brackets as follows: [LocalDomainServers] and [OtherDomainServers].

Creating a Single Copy Template


When a database is created from a template, all of the design elements are copied to and reside in this
new database. In an environment where many databases inherit from a single template, such as a mail
template, the redundancy of data is apparent. The Single Copy Template (SCT) feature in Domino Release
6 and later, when enabled in a template, results in the replacement of design elements in the inheriting
databases on the same server with pointers or reference notes. These reference notes point to the
associated design element in the template in a fashion that is transparent to the end user. In this way,
design notes are stored only once on the server. Any modifications of design elements in a database
inheriting from a single copy template will result in a full copy of that design note in the database.

When databases and/or replicas are created from a single copy template they will initially contain full
design notes. It is the Design task which performs the work of creating and removing reference notes
from a database. Reduction of database size (disk space) is a major advantage of using single copy
templates and will be realized upon compaction of the databases.

To create/enable a single copy template


The following is the recommended way of creating a single copy template:
1. (Recommended) - Identify a template on a server to be designated as a SCT (mail6.ntf for example).
Create a copy of this template (named mail6sct.ntf) to a local area.
2. Open the Database Properties box (File->Database->Properties) of this new copy (mail6sct.ntf) and in
the Design tab, change the template name from StdR6Mail to StdR6MailSCT. You may opt to have this
new template inherit design changes from the original, StdR6Mail. Also, click the checkbox labeled
″Single Copy Template″.
3. Copy this template back to the server.
4. Change the inheritance of any/all databases which inherit from mail6.ntf (StdR6Mail) to mail6sct.ntf
(StdR6MailSCT). This can be done most easily through use of the convert utility as follows
(recommended with the server down):
a. Convert all user files in the ’mail’ subdirectory that currently inherit from StdR6Mail to use
mail6sct.ntf
$ nconvert mail\*.nsf StdR6Mail mail6sct.ntf
Refer to documentation on the convert utility for additional information.

Tip: On Unix systems, use the convert command ″convert″ rather than ″nconvert″.

You can also do the following to create a single copy template:


v Identify a template on a server to be designated as a SCT (mail6.ntf for example). Enable Single Copy
Template on this template by selecting the Design tab of the Database Properties box and checking the
box labeled ’Single Copy Template’. The next time the design task is run, design elements will be
replaced with reference notes in each database which inherits from mail6.ntf. The design task typically
runs as a scheduled task overnight, but can be invoked on the server console as follows:

> load design

Chapter 20. Completing an application and managing design changes 421


Disabling Single Copy Template
Should a template designated as a single copy template become corrupt, it is simply a matter of
converting the user files back to use the original template. To disconnect a database from a single copy
template so that the database contains full design notes rather than reference notes, perform the following
depending on the deployment method used:
1. If method 1 above was used, then the original template (mail6.ntf) is still intact and unmodified.
Any/all users can be converted back to use this template as follows:
a. Convert user John Doe’s mail file back to use the original template.
$ nconvert mail\jdoe.nsf StdR6MailSCT mail6.ntf
b. Convert all users’ mail files in the ’mail’ subdirectory back to use the original template.
$ nconvert mail\*.nsf StdR6MailSCT mail6.ntf

2. If method 2 above was used, open the Database Properties box of the template (mail6.ntf) and uncheck
the ″Single Copy Template″ checkbox. Run the design task to place full design notes back into the
database.
> load design

Note: In addition to these methods, administrators may want to make an OS-level copy of a template,
and store it in a ″safe″ place. It is small, and is easily restored.

Notes/Restrictions
v Templates to be designated as Single Copy Templates must be Notes Domino ODS (43).
v Templates that have ever been marked as Single Copy Template cannot be deleted. This is to prevent
unresolved references. They must be deleted at the OS-level, if desired.
v A template that has ever been marked as Single Copy Template cannot have its design replaced at this
time.
v Do not change the name of the single copy template since databases which reference the template may
lose their association.
v Major conversions to/from SCT should be performed with the server down or during hours when
server activity is low.

Creating a design library template


If you have several design elements that you want to copy to different databases, you can create a library
of design elements. You do this by creating a template that contains all of these design elements. That
way, if you want to copy a design element to a new database, you maintain a connection to a source
template. This allows you to have a design library template that is maintained and updated centrally and
have the changes automatically propagate to all databases that you choose to inherit from that template.
This is especially useful if you have forms or images that will be common to a number of different
databases that need occasional updating, such as company logos or order forms.

422 Application Development with Domino Designer 7


To create a design library template
1. Create a new blank database with the file extension NSF.
2. Copy the individual design elements into the template.
3. Choose File - Database - Properties to open the Database Properties box.
4. Click the Design tab, select ″Database is a template,″ and enter a template name.
5. Open the Database Properties boxes of the design elements, click the Design tab, select ″Inherit from
the design template,″ and type the template name.

Linking a database to a template


You can link a new or existing database to a template.

To link a new database to a master template


When you create a database from a template, select ″Inherit future design changes″ in the New Database
dialog box to create the link.

When you create a replica (choose File - Replication - New Replica) or a copy (choose File - Database -
New Copy), the new database automatically links to the same template that the original database uses.

To link an existing database to a template


If you link an existing database to a template, the database design is replaced when the server’s Designer
task runs, or when you manually refresh the design. Thereafter, the design remains synchronized with the
template.

Chapter 20. Completing an application and managing design changes 423


1. Select the template and choose File – Database – Properties.
2. Click the Design tab.
3. Highlight the name in the ″Database is a template″ box, and press CTRL+C to copy it.
4. Close the properties box for the template.
5. Select the database to link to the template.
6. Choose File - Database - Properties to open the Database Properties box.
7. Click the Design tab and select ″Inherit design from template.″
8. Click the Template Name box, and press CTRL+V to paste the name.

Linking individual design elements to a template


To link individual forms, views, navigators, pages, and other design elements to a template, copy the
design element from a template or from a database that inherits its design from a template. Then paste
the element into another database. You can also set up the link for existing design elements in a database
to a template.

To link a copied design element to a template


When you copy a design element from a template or from a database linked to a template, the copied
element automatically links to the template if you answer ″Yes″ when prompted about inheriting future
design changes.

To link an existing design element to a template


If you link an existing design element to a template, the design is replaced when the server’s Designer
task runs or when you manually refresh the design. Thereafter, the design element remains synchronized
with the template.
1. Select the master template and choose File – Database – Properties.
2. Click the Design tab.
3. Highlight the name in the ″Database is a template″ box and press CTRL+C to copy it.
4. Open the database containing a design element you want to link.
5. In the Design pane, select the type of design element you’re creating.
6. Select the name of the design element in the Work pane.
7. Do one of the following:
v For an agent, choose Agent - Agent Properties.
v For other design elements, choose Design - Design Properties.
8. Click the Design tab of the Design or Agent Properties box.
9. Click ″Inherit from the design template″ and press CTRL+V to paste the name.

Synchronizing databases with master templates


To use a consistent design for multiple databases, database designers can associate databases or elements
within databases with a master template. Designers can manually synchronize databases with a master
template, but more often they rely on the Designer task to do this. When a master template design
changes, the Designer task updates all databases that inherit their designs from the master template. The
Designer task runs daily by default at 1 AM. The Updall task, which runs by default at 2 AM, updates
the view indexes of databases changed by Designer.

For a server’s Designer task to update databases, you must create a replica of the master template on
each server that stores databases that inherit from the master template.

CAUTION:
To avoid inconsistencies during database updates, ensure that replicating servers do not update
simultaneously.

424 Application Development with Domino Designer 7


After updating database designs, the Designer task also reloads the LDAP schema on a Domino server
that runs the LDAP service. You can run the Designer task manually.

For more information on master templates, see the topic ″Creating a database from a template″ in the
chapter ″Creating an Application.″

For more information on the LDAP service, see Administering the Domino System.

To run the Designer task using the Task - Start tool


1. From the Domino Administrator, in the server pane on the left, select the server on which to run
Designer. To expand the pane, click the servers icon.
2. Click the Server - Status tab.
3. In the task panel on the right, click ″Task - Start.″
4. Select Designer and then click ″Start Task.″

To run the Designer task using a console command


1. From the Domino Administrator, select the server on which to run Designer in the server pane on the
left. To expand the pane, click the servers icon.
2. Click the Server - Status tab.
3. Click Console.
4. Enter the following command in the command line at the bottom of the console, and then press
ENTER:
Load design

Running the Designer task for a single database


If you want to refresh a single database, you can supply arguments to the design server command using
the following syntax:
design [source-server [dest-server]] [-f single-db-to-refresh] [-d [single-dir-to-refresh]]
1. From the Domino Administrator, select the server on which to run Designer in the server pane on the
left. To expand the pane, click the servers icon.
2. Click the Server - Status tab.
3. Click Console.
4. Enter the Load design command in the command line at the bottom of the console along with
optional arguments to refresh a single database or all of the databases in a single directory, and then
press ENTER.

Examples
v To refresh all databases in the mail directory:
design -d mail
v To refresh only the NAMES.NSF file:
design -f names.nsf
v To refresh only the USER.NSF in the mail directory:
design -f mail\user.nsf

Making and distributing design changes


When you need to redesign an application, make and distribute the changes in one of these ways:
v Make design changes directly in an independent database on the server.
This technique combines making and distributing design changes in one step. Use this technique only
if a small group of people uses the database and it exists on only one server.

Chapter 20. Completing an application and managing design changes 425


v Make design changes in a template and then use ″Replace Design″ to distribute the template design to
the database.
v Make design changes in a master template (sometimes called a ″design template″). Use the Designer
server task or Refresh Design to distribute the master template design to databases that inherit their
design from the master template.
Using a master template to manage design changes is best in larger organizations where you need to
control, track, maintain, and synchronize design changes in a structured way. For small organizations,
using a template or a master template is a matter of preference.

Note that replication is the process by which database replicas on multiple servers synchronize their data
and their designs automatically. It’s important to understand which design changes replicate and which
don’t and how the database access control list and other replication settings affect the distribution of
design changes.

This figure below summarizes the steps you take to make and distribute design changes to different
types of databases.

Refreshing a design
Refreshing a design updates a database whose design is linked to a template. Design elements that
prohibit design replace or refresh are not included in the updates.

If you use a template to refresh or replace the database design, to ensure that the option ″Prohibit design
refresh or replace to modify″ takes effect, select this option as well as the option ″Propagate this
prohibition of design change″ in the design properties of the template.

Automatically refreshing a design


The Designer server task automatically synchronizes all server databases that are linked to a template.
This server task runs by default at 1:00 AM. For the update to work, a template must reside on the same
server as the databases linked to it. Replicas synchronize with the templates stored on their servers.

426 Application Development with Domino Designer 7


Manually refreshing a design
Use the Refresh Design command to distribute design changes manually from a template to any
databases linked to it. Manually refresh the design of a database when:
v The database is stored locally; therefore, the nightly Designer server task doesn’t update the design.
v You want to receive design updates before the scheduled update.
v You don’t have Designer access to the database.

Components that are not refreshed


The following are not changed during an automatic or manual refresh procedure:
v The database icon (unless you have disabled the ″Prohibit design refresh or replace to modify″ box in
the Design Properties box)
v The database title and category
v The database ACL and encrypt database settings
Note that the ACL roles are updated (File - Database - Access Control - Roles).
v The ″Using Database″ and ″About Database″ documents (unless you have disabled the ″Prohibit design
refresh or replace to modify″ box in the Design Properties box)
v Individual elements whose design is protected from updates (that is, if ″Prohibit design refresh or
replace to modify″ is selected in the Design Properties box for the element)
v A component whose template, specified in the ″Inherit from the design template″ box in the Design
Properties box, is unavailable

CAUTION:
An element with inheritance set is not replaced even if its design is not protected from updates (that
is, if ″Prohibit design refresh or replace to modify″ is not selected).
v The ″List as advanced template in ’New Database’ dialog″ option on the Design tab of the File -
Database Properties box
v All options on the Advanced tab of the File - Database Properties box, except ″Document table bitmap
optimization″ and ″Don’t support specialized response hierarchy″

Components that are refreshed


The following components are changed during an automatic or manual refresh procedure if the design
element changes in the template:
v Forms, fields, form actions, and event scripts
v Views, folders, and view actions
v Agents
v Pages
v Framesets
v Navigators
v Shared fields
v All Database Properties box options, except ″List as advanced template in ’New Database’ dialog″ on
the Design tab
v The options ″Document table bitmap optimization″ and ″Don’t support specialized response hierarchy″
on the Advanced tab of the File - Database Properties box

Refreshing a design manually


1. Select the database to be updated, and choose File - Database - Refresh Design.
2. Select the Domino server that stores the template(s) or select Local if the templates are on your
workstation, and then click OK.

Chapter 20. Completing an application and managing design changes 427


3. Click Yes to confirm.
4. Repeat Steps 2 and 3 if other templates associated with the database are stored on other servers.

Replacing a design
The Replace Design command makes a database identical to a template and is the only way to distribute
design changes if the database doesn’t inherit its changes from a template. If you have at least Designer
access in the database ACL, you can replace the design of a database with the design from a template.

If you use a template to refresh or replace the database design, to ensure that the option ″Prohibit design
refresh or replace to modify″ takes effect, select this option as well as the option ″Propagate this
prohibition of design change″ in the design properties of the template.

Components that are not replaced during Replace Design


The following components are not changed during a Replace Design procedure:
v The database icon (unless you have disabled the ″Prohibit design refresh or replace to modify″ box in
the Design Properties box)
v The database title and category
v The database ACL and encrypt database settings
Note that the ACL roles are updated (File - Database - Access Control - Roles).
v The ″Using Database″ and ″About Database″ documents (unless you have disabled the ″Prohibit design
refresh or replace to modify″ box in the Design Properties box)
v Individual elements whose design is protected from updates (that is, if ″Prohibit design refresh or
replace to modify″ is selected in the Design Properties box for the element)
v Individual elements whose template is inherited (that is, if ″Inherit from the design template″ is
selected in the Design Properties box for the element)

CAUTION:
An element with inheritance set is not replaced even if its design is not protected from updates (that
is, if ″Prohibit design refresh or replace to modify″ is not selected).
v The ″List as advanced template in ’New Database’ dialog″ option on the Design tab of the File -
Database Properties box
v All options on the Advanced tab of the File - Database Properties box, except ″Document table bitmap
optimization″ and ″Don’t support specialized response hierarchy″

Components that are replaced during Replace Design


The following components are replaced during a Replace Design procedure:
v Forms, fields, form actions, and event scripts
v Pages
v Views, folders, and view actions
v Agents
v Navigators
v Framesets
v Shared fields
v Database Properties selections, except the ″advanced template″ option
v All options on the Design tab of the File - Database Properties box, except ″List as advanced template
in ’New Database’ dialog″
v The options ″Document table bitmap optimization″ and ″Don’t support specialized response hierarchy″
on the Advanced tab of the File - Database Properties box

428 Application Development with Domino Designer 7


To replace the design of a database
If a database replicates to other servers, replace the design of only one database and let the changes
replicate to other replica databases.
1. Select the database on the server and choose File - Database - Replace Design.
2. Select the template.
3. Click Replace and Yes to confirm.

Design changes and replication


Unless you distribute design changes through templates, design changes and any document updates
made in one database replicate directly to replicas, as long as servers have Designer access or greater in
the database ACL. To avoid replication conflicts and unexpected changes, only one person -- the database
designer or manager -- should make design changes to only one database and maintain its design. Then
let replication distribute the design changes to other replicas.

Replication occurs at the times specified by the server’s replication schedule. Replicating design changes
can take several hours or even a full day if replicas are in different locations and aren’t replicated
frequently.

Templates and replication


When you use a template to distribute design changes, you must place a replica of the template on each
server that has databases that inherit their design from the template. Give servers Designer access or
greater in the database ACL of each replica. To avoid replication conflicts, make changes to one template
on a ″source″ server. Then let replication distribute the design changes to template replicas. The updated
template replicas then refresh the design of linked databases on the server. To distribute design changes
efficiently, the source server should replicate the template replicas before the Designer task runs on each
server at 1:00 AM. Any updates you’ve made to documents replicate directly with other database
replicas.

For more information on replication, see Administering the Domino System.

Preventing design changes


Use these methods to protect a customized design from accidental changes.

Note: None of these choices prevents someone with Designer or higher access in the database ACL from
changing the design. To prevent all design changes, hide the design of the database and remove Designer
and Manager access from users who can change the design.

To protect individual design elements from being replaced or


refreshed
Use this procedure to protect customized design elements from being overwritten in a Replace Design
procedure and to protect a customized design element in a database that is linked to a template.
1. Open a database in Designer.
2. In the Design pane, click a design element. The names of all the design elements of that type appear
in the Work pane.
3. In the Work pane, select the name of the design element you want to protect.
4. Do one of the following:
v For an agent, choose Agent - Design Properties.
v For a script library, choose Edit - Properties (you can also choose Design - Design Properties).
v For other design elements, choose Design - Design Properties.

Chapter 20. Completing an application and managing design changes 429


5. Click the Design tab.
6. Select ″Prohibit design refresh or replace to modify.″

If you use a template to refresh or replace the database design, to ensure that the option ″Prohibit design
refresh or replace to modify″ takes effect, select this option as well as the option ″Propagate this
prohibition of design change″ in the design properties of the template.

To unlink individual design elements from a template


This procedure breaks the link between a design element and a template and is useful when you want to
customize a design element that you copied from a template. Future changes to the design element in the
template won’t affect the design element in your database.
1. Open a database in Designer.
2. In the Design pane, select a design element. The names of all the design elements of that type appear
in the Work pane.
3. In the Work pane, select the name of the design element you want to unlink.
4. Do one of the following:
v For an agent, choose Agent - Agent Properties.
v For a script library, choose Edit - Properties.
v For other design elements, choose Design - Design Properties.
5. Click the Design tab.
6. Remove the name of the template in the ″Inherit from the design template″ box.

To unlink a database from a template


This procedure breaks the link between a database and a template and is useful when you want to
customize the design of an entire database. Future changes to the template won’t affect the database.
1. Open the database and choose File - Database - Properties.
2. Click the Design tab.
3. Deselect ″Inherit design from template.″

Modifying multiple design elements


To save time, you can select multiple design elements and set their common design properties. For
example, you might want to prevent all of the forms in your application from inheriting changes from a
template or hide a collection of views from Web users or Mobile users.
1. Open a database in Designer.
2. In the Design pane, click the name of a design element (for example, Forms). The names of all the
design elements of the specified type appear in the Work pane.
3. In the Work pane, select the name of a design element that you want to modify, then hold down
SHIFT and select the other contiguous elements you want to modify, or hold down CTRL and select
the elements you want to modify.
4. Choose Design - Design Properties. The Design Properties box shows only the properties that you can
set for the selected elements. The properties box displays initial values that are the same for all
selected design elements. Properties that are set differently for different design elements display with
a gray check.
5. Set properties for the selected elements. For example:
v Enter a template name to have the selected elements inherit from one template.
v Check ″Prohibit design refresh or replace to modify″ to prevent the selected elements from being
modified during a refresh or replace.

430 Application Development with Domino Designer 7


If you use a template to refresh or replace the database design, to ensure that the option ″Prohibit
design refresh or replace to modify″ takes effect, select this option as well as the option ″Propagate
this prohibition of design change″ in the design properties of the template.
v Check ″Propagate this prohibition of design change″ so that if a database inherits the selected
design elements, the ″Prohibit design refresh or replace to modify″ option will be inherited also,
and it will apply to the same elements in replicas of the database.
v Hide the design elements from Web browsers, Notes clients, or Mobile users.

Hiding the design of a database


To prevent users from making any design change to a database, hide the database design. Hiding the
design disables all design operations and hides all formulas and scripts.

CAUTION:
Users who have Designer or Manager access to the database can replace the database design, thereby
changing it. To fully protect database design, remove Designer and Manager access from users who
can change the database design.

This feature is useful for hiding the design of databases that are based on a template you own. When
design changes are required, you redesign the template, whose design is not hidden, and then refresh the
design of the linked databases. To maintain maximum design security, do not give the template to anyone
except authorized designers, and do not distribute documentation for the formulas and LotusScript
programs.

When you hide a database design, users cannot:


v View the settings for design elements (View - Design disappears from the View menu)
v Modify, add, or delete fields, forms, navigators, pages, or subforms
v Modify or delete existing views
v View, delete, or modify existing agents or add shared agents
v View or change formulas, LotusScript programs, or formulas associated with simple actions
v Change the Database Open properties
v Display a synopsis of the design
v Reveal the design of the database by making a copy or replica of it

To hide the design of a database


This procedure assumes you’re hiding the design of a database that inherits from a template. Thoroughly
review, debug, and test the template before proceeding.
1. Create a new database based on the template.
2. After the database is created, select the new database and choose File – Database – Replace Design.
3. From the list of templates displayed in the dialog box, choose the template from which the selected
database inherits its design.
4. Check both ″Inherit future design changes″ and ″Hide formulas and LotusScript.″
5. Click Replace and Yes to confirm.

Building in access to agents before hiding the design


If an agent in the application requires user input, such as specifying a database on which to run or
changing schedule options, you must select the schedule option ″Choose when agent is enabled″ (On the
Basics tab of the Agents Properties box, select ″On Trigger″ and then click Schedule). Create a button or
form or view action that includes a formula using @Command[AgentEnableDisable] to enable the agent
automatically.

Chapter 20. Completing an application and managing design changes 431


Hiding design elements
You can hide most design elements so that users can’t see them on menus or lists. You do this in the
Design tab of the Properties box for the design element or agent.

Choose from these options at the Design tab:

″Hide design element from″


Choose ″Web browsers″ to hide a Notes- or Mobile-only design element from Web users.

Choose ″Notes R4.6 or later″ to hide a Web- or Mobile-only design element from Notes users.

Choose ″Mobile clients″ to hide a Notes- or Web-only design element from Mobile users.

Choose all options to hide the design element from all users. This is useful when a design element
launches only from a button or a formula, or if you designed the element for purposes that users don’t
need to know about.

″Do not show this design element in menus of Notes R4 or later


clients″
Use this to hide older design elements from Notes Release 4 or later users.

Hidden design elements are hidden from the server too; you can’t use Domino URL commands to access
documents in hidden views or forms.

Tip: To hide a design element that isn’t needed by users but is used for background processes, such as
lookup formulas, enclose the design element name in parentheses -- for example, (Lookup View) --
instead of using Hide When tab options.

To hide design elements


1. Open a database in Designer.
2. In the Design pane, select a design element.
3. In the Work pane, select the name of the design element you want to hide.
4. Do one of the following:
v For an agent, choose Agent - Agent Properties.
v For a script library, choose Edit - Properties.
v For other design elements, choose Design - Design Properties.
5. Click the Design tab.
6. Choose the appropriate Hide When options.

Locking a design element


If you work on a team and want to ensure that other designers cannot modify design elements that you
are working with, you can explicitly lock them. When you have finished working with the design
elements and want to release them so that others can modify them, you can unlock them. (A design
element that is not explicitly locked is always temporarily locked while it is being edited. After the
designer has finished editing the design element, the temporary lock is released.)

Shared Actions are contained in one design note. Therefore, when you lock a Shared Action, you lock all
Shared Actions. Likewise, when you unlock a Shared Action, you unlock all Shared Actions.

432 Application Development with Domino Designer 7


To enable design element locking
Enable design element locking when you want to give designers the ability to lock and unlock any of the
design elements in a database.
1. Open the database.
2. Choose File - Database - Properties and click the Design tab.
3. Select ″Allow design locking.″
Now designers can explicitly lock design elements in the database. A newly created column next to
the design element name indicates the lock status of the design element.

To lock a design element


Lock a design element when you want to ensure that you have exclusive ownership of it and to prevent
others from modifying it.

CAUTION:
If you work locally or offline and attempt to lock a design element, Designer displays a message
stating that the ″Master lock database cannot be reached″ and asks if you want to proceed with
locking the design element. If you click Yes to proceed, the database applies a provisional lock to the
design element. When you connect again and replicate, the database attempts to convert the
provisional lock to a true lock. If it is successful, the database saves the edits that you made to the
design element. If it is unsuccessful, the database sends you mail containing the edits that the
database could not save; you must apply them manually to the design element.
1. Highlight the design element in the Work pane.
2. Right-click the design element and select Lock.
If the design element was unlocked, a padlock icon appears in the Work pane indicating that you
have successfully locked the design element, and a message appears on the status bar. You now have
exclusive access to the design element; other designers cannot modify it.
If someone else has locked the design element, a lock-and-key icon appears in the Work pane.

To unlock a design element


Unlock a design element when you have finished making changes to it and want to allow others to be
able to modify it. You can unlock only design elements that you have locked. Designers with Manager
access to the database can unlock any design element.
1. Highlight the design element in the Work pane.
2. Right-click the design element and select Unlock.
If you had locked the design element, the padlock icon disappears in the Work pane indicating that
you have successfully unlocked the design element, and a message appears on the status bar. You no
longer have exclusive access to the design element; other designers can now modify it.

To disable design element locking


Disable design element locking when you want to prevent designers from explicitly locking design
elements in a database.
1. Choose File - Database - Properties and click the Design tab.
2. Deselect ″Allow design locking.″
Now designers cannot explicitly lock design elements in the database.

Chapter 20. Completing an application and managing design changes 433


434 Application Development with Domino Designer 7
Chapter 21. Deploying an application
The tasks involved with application design, database design, database management, and Lotus®
DominoTMsystem administration may overlap, depending on the size of your organization and the
structure of job responsibilities. In some organizations, an application developer may be responsible for
both application and database design, while in others, a database manager may handle all database
design and management tasks. In addition, database management overlaps with Domino system
administration.

Therefore, depending on your organization, make sure you work closely with the people who are
responsible for design, management, and administration tasks. For example, controlling user access is
primarily a Domino system administrator’s responsibility, yet the application developer may determine
user access levels because they are often integral to the database design. If you need to make design
changes after a database is in production, be sure to:
v Work with the Domino administrators to implement and coordinate design changes
v Consult with Domino administrators when putting databases on servers, because administrators are
aware of server resources and the connections between servers
For more information on designing or redesigning databases, see Lotus Notes and Domino Release Notes.
For more information on rolling out a database, as well as information on Domino administration, see
Administering the Domino System.

Rolling out a database


As you roll out your application, you need to work closely with your Domino server administrator to
organize your application on a server and perform a set of administrative tasks. The following tables list
the mandatory and optional tasks that the Domino administrator performs to put a database into
production. You must have Manager access in a database access control list (ACL) to perform these tasks.

Mandatory tasks
Perform these tasks before you copy a new database or database replica to a production server.

For more information on the following tasks, as well as information about replication, see Administering
the Domino System.

Task Considerations
Set up the database ACL for users and If you plan to make replicas of a database, make sure that the
servers that require access database ACL lists the name of each server containing a replica. If
the database uses roles, assign all roles to each server.

If you assign ACL settings on the original database before copying it


to a server, assign yourself Manager access on the original.
Otherwise, you won’t have Manager access to the new copy.
Verify that server ACLs are set up correctly Without proper access in a server ACL, users and servers won’t
have access to databases on the server.
Verify that the Domino Directory contains the Create a Group document in the Domino Directory before adding a
necessary Group documents Group name in a database ACL. Make sure that the Group
document replicates before you copy the database to a server.
Copy the new database to a server Consider server disk space, topology, and network protocols. Placing
a database on a cluster requires that you consider cluster resources.

435
Task Considerations
Verify that the database appears in the Open While designing a database, the database designer often removes the
Database dialog box database title from the list that appears in the Open Database dialog
box. This deters the user from opening the database. After the
database is completed, make sure that the database title appears in
the Open Database dialog box.
Decide which servers require replicas of the To make this decision, consider the purpose and size of database,
database and then create the replicas the number and location of users who need access to the database,
and the existing replication schedules between servers.
Verify that Server documents in the Domino Server documents are, by default, enabled for replication, but to
Directory are enabled for replication avoid any problems, verify this setting.
Create or edit Connection documents If several servers have a replica of the database, make sure that any
necessary Connection documents are set up so that replication can
occur.
Set up a replication schedule Consider the location and time zones of users and the frequency of
database updates needed.

Optional tasks
The following tasks are not required, but you may want to perform them after your database is in
production. Whether or not you need to do these tasks depends on the type of database you are rolling
out to the production server and the roles assigned to an application developer, database manager, or
Domino administrator in your organization.

For more information on the following tasks, as well as information about replication, see Administering
the Domino System.

Task Considerations
Create ″About this database″ and ″Using this Provide the name, phone number, and e-mail address of database
database″ documents managers in the ″About this database″ document. Provide
information about the application in the ″Using this database″
document.
Create an index for the database Create a full-text index for the database if users need to search the
database for information. If you create the index before you copy a
For information, see Administering the Domino new copy of the database or a replica to a server, the index settings
System. carry over to the new copy or replica.
Distribute encryption keys. If the database design includes encrypted fields, distribute
encryption keys to users.
Create a Mail-In Database document. If the database is designed to receive mail, you must create a
″Mail-In Database″ document in the Domino Directory.
List the database in the database catalog. By default, all databases are listed in the database catalog. If you
wish, add categories to control how the database appears in the
For information, see Administering the Domino catalog views.
System.
Publish the database in a database library. Create a library of selected databases on one server or several
servers for your users.
For information, see Administering the Domino
System.
Notify users that the database is available. Provide the database title, file name, and server location.

436 Application Development with Domino Designer 7


Copying a new database to a server
Plan the deployment of new databases before you copy them to a server. Tasks to plan with your server
administrator include:
v Set up Server documents in the Domino Directory, including a Mail-In Database document if the
database is designed to receive mail.
v Make sure that users and other servers are listed in the server’s access control list.
v Group related databases in subdirectories rather than copy them to the root directory so that users can
find related databases more easily. This grouping also helps administrators to replicate ″like″ databases,
because Connection documents let you replicate according to directory.
For more information on replication and server documents, see Administering the Domino System.

To copy a new database to a server


1. Make sure that you have Manager access in the database ACL or the ″Create new databases″ privilege
in the Server Access section of the Server Document in the Domino Directory.
2. Select the database icon from your bookmarks page. Choose File - Database - Properties, click the
Design tab, and make sure that ″Show in ’Open Database’ dialog″ is selected.
3. Choose File - Database - New Copy.
4. Next to Server, click the arrow to display a list of servers. Then select the server on which you want
to place the copy.
5. Next to Title, enter a title for the database. The database icon and the Open Database dialog box
display this title.
6. Next to File Name, enter the path and file name of the database. Limit the file name to eight
characters plus the NSF extension.
7. Choose one:
v ″Database design and documents″ to copy the database design and all documents.
v ″Database design only″ if you do not want to copy any pre-existing documents.
8. Optional steps:
v Choose ″Access Control List″ to copy the ACL.
You can assign ACL settings (including roles) before or after you copy a local database to a server.
Before you copy the database, assign yourself Manager access to the ACL so that you will have
Manager access to the new copy. If you do not copy the ACL when you copy the database to a
server, the ACL in the new copy automatically lists you with Manager access.
v Select ″Create Full Text index″ to create a full-text index on the new copy.
You can also create a full-text index at a later date.
v Choose Encryption to encrypt the new copy of the database.
This option is intended to prevent unauthorized users from accessing a database from a
workstation, laptop computer, or server. If you use this option, Notes encrypts the database using a
specified ID and only a user with that ID can gain access to the database. You can choose one of
three encryption levels. This encryption setting also carries over to copies of the database made at
the operating system level.
v To allow a database to grow beyond the default 1GB limit, click ″Size Limit,″ select a size, and click
OK. This option applies only to Release 4 format databases.

Note: The maximum size for a Release 4 database is 4GB. The maximum size for Release 5 and
later databases is 64GB on Windows and UNIX and 32GB on OS/2.
For more information on encryption, see the chapter ″Application Security.″

Chapter 21. Deploying an application 437


Setting up replication for an application
As you prepare to deploy an application, you must work with your Domino server administrator to
create a replication plan. Replication allows replica copies of databases to exchange updates. You can
replicate both design elements and database content between replica copies. Replication can be
unidirectional -- for example you can push out design changes but not receive any, or it can be
directional, in which cases changes are both sent and received. Generally you perform design work on
one copy of a database -- for example, you might keep a copy on your local hard drive -- then you
replicate design changes to database replicas on servers.

The following topics describe the tasks involved with creating and maintaining replicas. If you have full
access rights to post a database on a Domino server you can perform these tasks yourself; if not, you
need to work with a server administrator to create and maintain replicas.

Creating one replica manually


Follow these steps to create one replica of a database if you don’t have access to the Domino
Administrator or if you want to customize settings for the replica as you create it.
1. Make sure that you:
v Have Create Replica access in the Server document of the destination server.
v Have at least Reader access in the ACL of the databases on the source server.
2. Make sure that the source server:
v Has Create Replica access in the Server document of the destination server.
v Is cross-certified with the destination server if the two servers are in different Domino domains
and don’t share a common certifier.
3. Make sure that the destination server:
v Has at least Reader access in the ACL of the source replica.
v Is cross-certified with the source server if the two servers are in different Domino domains and
don’t share a common certifier.
4. Open the database.
5. Choose File - Replication - New Replica.

Note: Do not choose File - Database - New Copy to create a replica. If you use this command, the
replica ID of the copy is different from the original, and the two databases can’t replicate.
6. Next to Server, click the arrow and select the destination server on which you want to place the new
replica.
7. Specify the file name and title for the new replica. Any file name you choose must be unique to the
workstation or server on which you place the replica. The file name doesn’t replicate. To put the
replica in a folder within the data folder, next to File name type the folder name, backslash, and then
the file name -- for example, JOBS\POSTINGS. If the specified folder does not exist, Domino creates
it for you.
8. (Optional) Click ″Replication settings″ to select replication settings for the new replica.
9. (Optional) Click Encryption, select ″Locally encrypt this database using,″ and click OK to encrypt the
database with the server ID file. Choosing this option prevents users from copying or replicating the
database to their workstations and prevents users from accessing the database directly at the server.
This feature works only if the database ACL specifies the server as the user type ″Server″ or ″Server
group.″
For more information on encryption, see the chapter ″Application Security.″
10. (Optional) For Release 4 format databases only: To allow a database to grow beyond the default 1GB
limit, click ″Size Limit,″ select an option, and click OK.
For more information, see the chapter ″Optimizing Database Performance and Size.″

438 Application Development with Domino Designer 7


11. Choose one of the following:
v ″Create: Immediately″ to populate the new replica now. You must wait while all information
replicates to the new replica.
v ″Create: Next scheduled replication″ to create a replica stub that is populated when the destination
server next replicates with the source server. Consider selecting ″Create: Next scheduled
replication″ if the database is large or you’re creating a series of replica databases and you don’t
want to wait while the initial replication of documents occurs.
12. Select ″Copy Access Control List″ to copy the ACL from the original to the new replica. If you want
to be a Manager of the new replica, make sure you have Manager access in the ACL of the original.
Or to automatically give yourself Manager access to the new replica, deselect ″Copy Access Control
List.″ Make sure the server on which you’re creating the replica is included in the ACL and any
design element access lists.
13. (Optional) Select ″Create full text index for searching″ to create a full-text index on the new replica.
For more information on full-text indexes, see Administering the Domino System.
14. Click OK.

Replication settings
By default, two replicas exchange all edits, additions, and deletions if the servers the replicas are on have
the necessary access. However, you can customize replication. For example, to save disk space, you can
prevent the transfer of irrelevant documents. Using replication settings, you can:
v Limit the contents of a replica
v Limit what a replica sends to other replicas
v Assign miscellaneous replication settings, such as a replication priority

You can specify replication settings when you create a replica or on an existing replica. You can specify
some replication settings for multiple replicas at once from one replica. You must have Manager access to
a replica to set replication settings for it.

CAUTION:
Replication settings are not intended to be used as a security measure.

This table summarizes the available replication settings. An asterisk (*) marks the settings you can
manage for multiple replicas from a central source replica.

Panel in File - Replication -


Setting Controls Settings dialog box
Remove documents not modified in the When Domino purges document Space Savers panel
last x days deletion stubs and, optionally,
unmodified documents.
Only replicate incoming documents saved The cutoff date, so that a replica Other panel
or modified after: date only receives documents created or
modified since the date.

Which documents are scanned


during the first replication after
clearing the replication history.
Receive summary and 40KB of rich text The size of documents that a replica Space Savers panel
only receives.
Replicate a subset of documents* Which documents a replica receives. Space Savers panel

Advanced panel

Chapter 21. Deploying an application 439


Panel in File - Replication -
Setting Controls Settings dialog box
Replicate* Which non-document elements this Advanced panel
replica receives.
Do not send deletions made in this replica Whether a replica can send Send panel
to other replicas document deletions to other
replicas.
Do not send changes in database title and Whether a replica can send changes Send panel
catalog info to other replicas to the database title and Database
Catalog categories to other replicas.
Do not send changes in local security Whether a replica can send changes Send panel
property to other replicas to the Encryption database property
(in the Basics tab of the Database
properties box) to other replicas.
Temporarily disable replication Whether a replica can replicate. Other panel
Scheduled replication priority The replication priority of a Other panel
database used in Connection
documents for scheduling
replication.
CD-ROM publishing date The publishing date for a database Other panel
on a CD-ROM.

Limiting the contents of a replica


Use the following replication settings in the File - Replication Settings dialog box to limit the size of a
replica or to display a subset of information relevant to a particular group of users.

Remove documents not modified in the last x days (Space Savers panel)
The number of days specified here, known as the purge interval, controls when Domino purges deletion
stubs from a database. Deletion stubs are markers that remain from deleted documents so that Domino
knows to delete documents in other replicas of the database. Because deletion stubs take up disk space,
Domino regularly removes deletion stubs that are at least as old as the value specified. It checks for
deletion stubs that require removal at 1/3 of the purge interval. For example, assuming the default value,
90 days, when a user opens a database, Domino checks if it has been at least 30 days since it removed
deletion stubs, and if so it removes any deletion stubs that are at least 90 days old. The Updall task,
which runs by default at 2:00 AM, also removes deletion stubs.

You can shorten the purge interval, if you want, but be sure to replicate more frequently than the purge
interval; otherwise, deleted documents can be replicated back to the replica.

Optionally, you can select the check box to remove documents in the replica that haven’t changed within
the purge interval. If you select the check box, when Domino removes deletion stubs it also removes
documents that haven’t changed within the specified number of days. These documents are purged,
meaning no deletion stubs remain for the documents, so the documents aren’t deleted in other replicas.
The ″Only Replicate Incoming Documents Saved or Modified After: date″ setting prevents the purged
documents from reappearing through replication. If the other replicas have this check box selected,
similar document purging occurs in them.

CAUTION:
If you select the check box on a database that does not replicate, documents are lost and you can only
recover them from a system backup.

Note: Domino regularly removes deletion stubs according to the purge interval even if you don’t select
the check box.

440 Application Development with Domino Designer 7


Only Replicate Incoming Documents Saved or Modified After: date (Other panel)
A replica can only receive documents created or modified since the date specified. If you clear the
database replication history, during the next replication, Domino scans only documents created or
modified since the date specified here. If you clear the date before clearing the replication history,
Domino scans all documents in the database.

Use this option in conjunction with clearing the replication history to solve replication problems. If you
clear or change this date, when Domino next purges deletion stubs, it resets the date to correspond to the
number of days specified in ″Remove documents not modified in the last x days″ setting. For example, if
Domino purges deletion stubs on 1/1/99 and the ″Remove documents not modified in the last x days″
setting is 90, on 1/1/99 Domino resets the date to 10/1/98. If the check box is selected in the ″Remove
documents not modified in the last x days″ setting -- meaning documents that meet the purge interval
criteria are purged as well as deletion stubs -- this automatic date reset ensures that the purged
documents aren’t replicated back into the replica.

For more information on the replication history, see Administering the Domino System.

Receive summary and 40KB of rich text only (Space Savers panel)
If you select this setting, Domino prevents large attachments from replicating and shortens the documents
that this replica receives. The shortened documents contain only a document summary that includes basic
information, such as the author and subject, and the first 40KB of rich text.

When users open a shortened document, they see ″(TRUNCATED)″ in the document title. To view the
entire document, users must choose Actions - Retrieve Entire Document from the open document.

Keep the following points in mind when using this setting:


v Users can’t categorize or edit shortened documents.
v Agents don’t work on shortened documents.
v Shortened documents replicate only if the destination replica also has this option selected.

Replicate a subset of documents (Space Savers Advanced panel)


Use this setting to specify that a replica receives only the documents in a specific folder or view or only
documents that meet selection criteria specified in a formula. Replication formulas are similar to view
selection formulas.

For more information on view selection formulas, see the chapter ″Designing Views.″

Keep in mind the following points when you use replication formulas:
v You cannot use @DbLookup, @UserName, @Environment, or @Now in a replication formula.
v Using @IsResponseDoc in a replication formula causes all response documents in a database to
replicate, not just those that meet the selection criteria. Use @AllChildren or @AllDescendants instead
and make sure the database performance property ″Don’t support specialized response hierarchy″ is
not selected.
For more information on database performance properties, see the chapter ″Optimizing and
Troubleshooting Databases.″

Replicate (Advanced panel)


Use this setting to control which non-document elements a replica receives. This table describes the
Replicate options:

Chapter 21. Deploying an application 441


Replicate Default Description
Forms, views, and so on Selected If selected, allows a replica to receive design changes, such as
changes to forms, views, and folders from a source replica.

If deselected, prevents a replica from receiving design changes.


Alternatively, you can assign source servers Editor access or
lower in the ACL; however, doing so prevents agents from
replicating.

Don’t select this option when you first create the replica because
the new replica won’t contain any design elements for displaying
information.
Agents Selected If selected, allows a replica to receive agents. If deselected,
prevents the replica from receiving agents, although the replica
still receives changes made by the agents.
Replication formula Not selected If selected, ensures that replication settings specified for multiple
destination replicas from one source replica can replicate. This
option is required if you’re using a central source replica to
manage replication settings for multiple replicas.
Access control list Selected If selected, allows the replica to receive ACL changes from any
server that has Manager access in the replica’s ACL.
Deletions Selected If selected, allows the replica to receive document deletions. If
deselected, the replica won’t receive deletions through replication,
but users assigned ″Delete documents″ access in the replica ACL
can still delete documents from the replica.
Note: If ″Do not send deletions made in this replica to other
replicas″ (on the Send panel of the Replication Settings dialog
box) is selected for the source replica, this replica won’t receive
deletions from the source replica, regardless of this setting.
Fields Not selected If deselected, the replica receives all fields in each document
received. If selected, you select a subset of fields to receive, but
you should only do this if you have a thorough knowledge of
application design.

If you’re replicating a Domino Directory, you can also choose


among minimal Address Book options. These options provide a
way for mobile users to replicate a small version of a Domino
Directory locally. The minimal Address Book options are also
available in the Space Savers panel.

Note that users can also use a mobile directory catalog to have
local access to names in a Domino Directory.

For information on directory catalogs, see Administering the Domino System.

Assigning miscellaneous replication settings


The Other panel of the Replication Settings dialog box includes these miscellaneous settings.

Temporarily disable replication


Select this option to temporarily suspend replication while you troubleshoot a problem. You can select
this for one database, or if you use the Domino Administrator, you can disable replication of multiple
databases. If a database is on a cluster server, disabling replication suspends both cluster replication and
scheduled replication.

442 Application Development with Domino Designer 7


Scheduled replication priority
You can assign a replication priority of High, Medium, or Low to a database. Then in a Connection
document, you can schedule replication so that databases of a particular priority replicate at specific
times. For example, you can schedule low-priority databases to replicate less frequently and schedule
high-priority databases to replicate more frequently. If you assign a different priority to two replicas, the
priority of the replica on the server that initiates the scheduled replication takes precedence.

Replication priority doesn’t apply to replicas on a server cluster. Cluster replication occurs whenever a
change occurs, not according to schedules in Connection documents.

For information on connecting servers for replication, see Administering the Domino System.

CD-ROM publishing date


Some organizations -- for example, publishing companies -- distribute databases on CD-ROM rather than
replicate them. To receive updates, users replicate with a replica on the organization’s server. The users
specify the date the information was published on the CD-ROM so that the first replication with the
organization’s replica scans only documents created or modified since the publication date. If users do
not specify the date, the initial replication unnecessarily scans the entire database, which can be a slow
process, especially if it occurs over a dial-up connection.

Limiting what a replica sends


Use these settings to limit what one replica sends to other replicas.

Do not send deletions made in this replica to other replicas


This setting prevents deletions made in this replica from replicating. As an alternative, you can deselect
the ACL option ″Delete documents″ for the server storing this replica.

Do not send changes in database title & catalog info to other replicas
This setting prevents changes made to this replica’s database title or Database Catalog categories from
replicating.

Do not send changes in local security property to other replicas


This setting prevents changes to the database Encryption property (set by choosing Encryption on the
Basics tab of the Database Properties box). Use this primarily to prevent changes made to this property
on a local replica from replicating to a server. For example, if this setting is selected and you disable the
Encryption property on a local replica, the property remains selected on a server replica.

For information on database ACLs, as well as information on the Encryption property, see the chapter
″Restricting Access to and Securing Parts of an Application.″

Specifying replication settings


You can specify replication settings for a single replica, or you can customize replication settings for
multiple replicas of a database from one central source replica and then replicate these custom settings to
the appropriate replicas. This approach to customizing replication allows you to centralize replication
management and requires that you know the replication requirements for each replica.

The only centralized replication settings you can specify are ″Replicate a subset of documents,″ to control
which documents a replica receives, and ″Replicate,″ to control which non-document elements a replica
receives.

Note that changing centrally-managed replication settings requires two replications for the changes to
take effect: the first replication to replicate the new settings from the source server to the destination
servers and a second replication to replicate based on the new settings. The second replication doesn’t
occur until the source database is updated in some other way; to force the new settings to take effect if
the source database isn’t updated, clear the replication history.

Chapter 21. Deploying an application 443


For information on clearing the replication history, see Administering the Domino System.

To specify replication settings for a single replica


1. Do one of the following:
v To specify replication settings for a replica as you create it, click ″Replication Settings″ in the New
Replica dialog box.
v To modify replication settings on an existing replica, open the replica and choose File - Replication -
Settings. This requires Manager access.
2. Click the Space Savers panel and then select/deselect options.
3. Click the Send panel and then select/deselect options to limit what the replica can send to other
replicas.
4. Click the Other panel and then select/deselect options.
5. Click the Advanced panel and then select/deselect any of the options under ″Replicate.″ Ignore the
options above ″Replicate;″ these are used for managing replication settings for multiple replicas of a
database from one central source replica.
6. Click OK.

To specify replication settings for multiple replicas from one source replica
1. Make sure you understand replication settings.
2. Make sure you have Manager access in the ACL of the central source replica. Make sure that the
central source replica has Manager access in the ACL of all destination replicas.
3. Do one of the following:
v Click ″Replication Settings″ in the New Replica dialog box to specify replication settings for a new
replica.
v Open the central source replica, and then choose File - Replication - Settings to modify existing
replication settings.
4. Click the Advanced panel.
5. To specify a destination server, click the computer icon next to ″When computer,″ specify the name
of the destination server, select ″Add Server,″ then click OK. To specify a Notes client as a
destination server, enter the Notes client’s hierarchical name.
6. To specify a source server, click the computer icon next to ″Receives from,″ specify the name of a
source server, select Add Server, then click OK. To specify the name of a Notes client as a source
server, enter the Notes client’s hierarchical name.
7. To delete a server that is selected as replication target, click either computer icon, select a server,
select Delete Server, then click OK.
8. To have the specified destination replica receive a subset of documents, click ″Replicate a subset of
documents″ and then specify the views or folders to replicate or specify a replication formula.
9. To specify which non-document elements the replica should receive, select appropriate options under
″Replicate.″ You must select ″Replication formula.″
10. Repeat Steps 5 through 9 for each additional destination and source server combination.
11. Click OK.

Examples of specifying replication settings for multiple replicas


The following examples describe scenarios for various types of replication.

Using the same replication settings for all destination servers


The Acme Corporation has a Technical Support database on the server Support-E/East/Acme, which
contains information about customer problems and problem resolutions. The database displays customer
suggestions made during the support calls in a view called Customer Suggestions. Acme has three
servers at satellite sales offices: Sales-Bos-E/East/Acme, Sales-Phil-E/East/Acme, and
Sales-Hart-E/East/Acme. The satellite sales offices are interested only in customer suggestions and not in

444 Application Development with Domino Designer 7


other details of technical support calls. Only the contents of the Customer Suggestions view replicate to
the satellite sales office servers. To accomplish this, it completes the replication settings dialog box on the
Technical Support database on Support-E/East/Acme as follows, replicating everything except field data.
Note that although the ″When computer″ box shows only Sales-Bos-E/East/Acme, there are similar
settings for Sales-Phil-E/East/Acme and Sales-Hart-E/East/Acme.

Using separate replication settings for each destination server


The Acme Corporation has a database called Sales Leads on the server Sales-E/East/Acme. Acme has
three servers at satellite sales offices: Sales-Bos-E/East/Acme, Sales-Phil-E/East/Acme, and
Sales-Hart-E/East/Acme. Each satellite sales office is interested only in leads pertaining to its area. Each
document in the Sales Leads database includes the field ″Office″ with one of these keywords selected:
Boston, Philadelphia, or Hartford. To replicate only sales leads pertaining to Boston to
Sales-Bos-E/East/Acme, Acme completes the replication settings dialog box on the Sales Leads database
on Sales-E/East/Acme as follows, using a replication formula to limit replication to documents
containing the keyword ″Boston″ along with all descendants of those documents.

Chapter 21. Deploying an application 445


Acme sets up replication from Sales-E/East/Acme to Sales-Phil-E/East/Acme and to
Sales-Hart-E/East/Acme in a similar fashion.

Note: Although these examples describe server-to-server replication, you could use similar settings to
configure replication between a central source replica and replicas on Notes clients. For example,
salespeople could replicate directly with the source replica and receive only leads pertinent to their areas.
To accomplish this, specify Notes users’ hierarchical names as destination servers.

Disabling and enabling replication of a database


You can disable replication of a database -- for example, to stop replication while you troubleshoot
problems. Then, after you correct the problem, enable replication again. You can disable and enable
replication of one database, or you can use the Domino Administrator, to disable and enable replication
of multiple databases at once.

To disable replication of one database


1. Open the database and choose File - Replication - Settings.
2. Select Other.
3. Select ″Temporarily disable replication″ and then click OK.

To enable replication again, repeat the procedure, but in Step 3 deselect ″Temporarily disable replication.″

To disable replication of multiple databases


To disable replication of multiple databases, you must use Domino Administrator.

For information on disabling replication of multiple databases, see Administering the Domino System.

446 Application Development with Domino Designer 7


Forcing a server database to replicate
Replication between database replicas on servers typically occurs according to schedules in Connection
documents. You might want to force replication between two replicas, rather than wait for replication to
occur on schedule, for example, you might force replication when you want to test replication settings or
troubleshoot replication problems. You can force replication either from a database or from the server
console.

For information on creating Connection documents to schedule replication between servers, see
Administering the Domino System.

To force replication from the server console


If you are a server administrator, you can use a database option with the Replicate, Pull, or Push server
commands to force replication of a specific database that two servers have in common.
v Use the Replicate command to send changes to and receive changes from a specified server.
v Use the Pull command to receive changes from a specified server.
v Use the Push command to send changes to a specified server.

For example, to send changes to the database PRODUCTS.NSF from the server Webstage-E/East/Acme
to the server Web/East/Acme, enter the following command from the server console on
Webstage-E/East/Acme:
Push Web/East/Acme Products.nsf

For more information on these commands, see Administering the Domino System.

To force replication from the database


1. Open the database.
2. Choose File - Replication - Replicate.
3. Select ″Replicate with options″ and click OK.
4. Select the server that stores the replica with which you want to replicate.
5. Select ″Send documents to server″ to send updates from the replica selected on your workspace to the
server selected in Step 4.
6. Select ″Receive documents from server″ to send updates from the server selected in Step 4 to the
replica selected on your workspace.
7. Click OK.

Chapter 21. Deploying an application 447


448 Application Development with Domino Designer 7
Chapter 22. Optimizing and troubleshooting databases
Set advanced database properties to:
v Optimize database performance
v Enable or disable transaction logging
v Allow more fields in a database
v Allow soft deletions
v Use LZ1 compression for attachments

Properties that improve database performance


Properly setting database properties can improve the performance of an active database. Setting database
performance properties on many databases or on one, large, active database can also improve server
performance. In addition, some of these property settings also help reduce the size of databases.

Many of these properties require knowledge of application design. Database designers often set these
properties when they create databases.

Display images after documents


To quickly display documents that contain images, select the Basics database property ″Display images
after loading.″ Then Notes users can read the text while the images load. If you don’t load images after
text, Notes loads images in the order in which they appear in a document; if an image appears first,
Notes loads it before displaying text. With large images or slow connections, loading images in order
may slow the display of the document.

This setting applies only when using Notes to view databases; Web browser settings control the display
of images to Web browser users.

Tip: Users also can specify ″Load images: On request″ in the Advanced section of a Location document
to display images only when users click them. For more information, see Lotus Notes Help.

Prevent the use of stored forms


To ensure that a document always displays correctly, you can store the form with the document.
However, storing a form with every document uses system memory and may require as much as 20
times more disk space than not doing so. To save memory and disk space, you may want to prevent the
use of stored forms, especially if users experience performance problems when trying to read the
documents. To prevent the use of stored forms, deselect the Basics database property ″Allow use of stored
forms in this database.″ Before preventing the use of stored forms, make sure you understand how this
design feature works and how the database uses it.

For information on storing a form with a document, see the chapter ″Designing Forms.″

Don’t maintain unread marks


Maintaining unread marks in a database requires system resources and can significantly slow database
performance. For some databases, unread marks aren’t useful -- for example, reference databases such as
the Help databases provided with Domino, administration databases such as the Domino Directory, or
databases such as the log file (LOG.NSF) that are continually updated. In these types of databases,
consider disabling unread marks. To disable unread marks, select the Advanced database property ″Don’t
maintain unread marks.″

449
Note: Designing views that don’t display unread marks doesn’t improve database performance because
they are still maintained but not displayed.

If you select or deselect the ″Don’t maintain unread marks″ property, you must compact the database so
that the setting takes effect. Compacting in this case makes a temporary copy of the database, so your
system must have the disk space to make the copy.

Tip: You can also run the Compact server task with the -u or -U option to enable or disable this property
and then compact.

For information on compacting databases, see the book Administering the Domino System.

Associate document tables with forms for view updates


When updating a view, Domino refers to tables of document information. These tables are stored
internally in the database. By default, during view updates and rebuilds, Domino searches each table for
documents that appear in the view being updated. To update views more efficiently, select the Advanced
database property ″Optimize document table map.″ This property associates tables with the forms used
by the documents the tables contain. Then during a view update, Domino searches only the tables
associated with the forms used by documents in the view being updated. This significantly improves the
performance of view updates, especially updates of small views within large databases -- for example, the
Connections view in the Domino Directory.

This property only works for views that use Form= as part of the selection criteria. There’s a slight
performance cost to maintaining the table/form association; however, when updating small views in
large databases, the benefits offset the cost.

If you select or deselect the ″Optimize document table map″ property, you must compact the database so
that the setting takes effect. Compacting in this case makes a temporary copy of the database, so your
system must have the disk space to make the copy.

Tip: You can also run the Compact server task with the -F or -f option to enable or disable this property
and then compact.

For information on compacting databases, see the book Administering the Domino System.

Prevent overwriting of deleted data


When data is deleted from databases, Domino, by default, overwrites the deleted data on disk with a
pattern. This pattern prevents an unauthorized user from using a utility to access the data. This
overwriting affects disk I/O and can affect database performance.

Preventing the overwriting of deleted data is appropriate in these circumstances:


v The data is already secure -- for example, the database is on a server in a locked room.
v Deleted space in the database is constantly reallocated -- for example, in a system database such as
MAIL.BOX.
v Data security isn’t an issue -- for example, in an informal discussion database.

To prevent the overwriting of deleted data, select the Advanced database property ″Don’t overwrite free
space.″

Don’t maintain ″Accessed (In this file)″ document property


The Document Properties box displays the property ″Accessed (In this file)″ which can show the date a
document was last modified or read. The Advanced database property ″Maintain LastAccessed property″

450 Application Development with Domino Designer 7


controls whether the ″Accessed (In this file)″ property is updated if the last document access was a read.
Maintaining the ″Accessed (In this file)″ property for reads causes disk I/O that wouldn’t otherwise
occur.

By default, the database property ″Maintain LastAccessed property″ is not selected, meaning the
″Accessed (In this file)″ property isn’t updated when the last document access was a read, only when the
last access was a document modification. Change the default behavior by selecting ″Maintain
LastAccessed property.″

You should select ″Maintain LastAccessed property″ if you use the document archiving tool, available in
the Database Properties box, to delete documents based on days of inactivity.

Disable specialized response hierarchy information


By default every document stores information that associates it with a parent document or a response
document. Only the @functions @AllChildren and @AllDescendants, which are often used in view
selection and replication formulas, use this stored information. Maintaining this information has a
significant, negative effect on database performance.

To improve database performance, disable the response hierarchy information in databases that don’t use
these @functions by selecting the Advanced database property ″Don’t support specialized response
hierarchy.″

Disabling the response hierarchy information has no effect on views and replication formulas that display
information hierarchically without using @AllChildren and @AllDescendants.

Disabling the response hierarchy information sets NotesDocument.Responses to 0 documents.

If you select or deselect the ″Don’t support specialized response hierarchy″ property, you must compact
the database so that the setting takes effect. Compacting in this case makes a temporary copy of the
database, so your system must have the disk space to make the copy.

Tip: You can also run the Compact server task with the -h or -H option to enable or disable this property
and then compact.

For information on compacting databases, see the book Administering the Domino System.

Disable transaction logging


Transaction logging captures all the changes made to a database and writes them to a transaction log. The
logged transactions are then written to disk in a batch, either when resources are available or when
scheduled. Disable the transaction log can improve database performance.

For information on transaction logging, see the chapter ″Transaction Logging and Recovery.″

Prevent headline monitoring


Users can set up headline monitoring to automatically monitor databases for information that interests
them. Monitoring a database this way affects performance, especially if many users do this. To prevent
users from monitoring a database, select the Advanced database property ″Don’t allow headline
monitoring.″

Administrators can also use the Security section of a Server document in the Domino Directory to control
headline monitoring at the server level.

Chapter 22. Optimizing and troubleshooting databases 451


Allow more fields in a database
You can increase the number of fields in a database by selecting the advanced database property ″Allow
more fields in database″ which allows the database to contain up to 23,000 fields.

For a database without this option selected, all the field names in a database when concatenated cannot
exceed 64 kilobytes, which results in a database limit of approximately 3000 fields.

Use LZ1 compression for attachments


In Lotus Domino Designer Release 6 and later, you can choose to compress attachments using the new
LZ1 algorithm instead of the Huffman algorithm. Because LZ1 compression can be performed quickly
and efficiently, it is favored over the Huffman method. However, if you are working in an environment
that uses different versions of client and server software (for example, a Lotus Domino Designer 6 client
and an R5 server) and you choose this option, attachments are automatically recompressed on the server
using the Huffman method. Note that recompressing has performance implications. For best performance,
use LZ1 in primarily Domino 6 or later environments.

Limit the size of $UpdatedBy fields


Every document includes an $UpdatedBy field that stores, by default, the name of the user or server
associated with each document editing session. Storing a complete edit history consumes disk space and
slows view updates and replication. To conserve disk space and improve database performance, use the
Advanced database property ″Limit entries in $UpdatedBy fields″ to specify the number of entries that
the $UpdatedBy field can contain. When the $UpdatedBy field reaches this limit, the oldest entry is
removed to make room for the newest entry.

Limit the size of $Revisions fields


Every document includes a $Revisions field that stores, by default, the date and time of each document
editing session. Domino uses this field to resolve replication or save conflicts that occur when two users
simultaneously edit the same document on one replica or edit the same document on different replicas
between replications.

By default, the $Revisions field stores a history of up to 500 edit sessions, each of which requires 8 bytes
of disk space. Over time, $Revisions fields can grow large, taking up disk space and slowing view
updates and replication. To conserve disk space and improve database performance, use the Advanced
database property ″Limit entries in $Revisions fields″ to specify the number of entries that the $Revisions
field can contain. When the $Revisions field reaches this limit, the oldest entry is removed to make room
for the newest entry.

Consider limiting the entries in $Revisions fields on a database with all of the following characteristics:
v The database contains many documents.
v The database replicates often or has no replicas.
v The database contains documents that are not often edited.

A suggested upper limit is 10 entries in the $Revisions field. If you set the limit lower than 10, you run
the risk of increased replication or save conflicts.

Specify expiration time for soft deletions


When ″Allow soft deletions″ is selected, documents marked for deletion are held in the database for a
specified time before they are deleted. On the Advanced tab of the Database Properties box, you can
specify the number of hours documents are held before they are deleted from the database.

452 Application Development with Domino Designer 7


To set database properties that optimize database performance
You can set database properties to optimize database performance and to reduce database size. Set
database performance properties by opening the Database Properties box on an existing database or as
you create a database.

Make sure you fully understand these database properties before changing their settings.
1. Make sure you have Designer or Manager access in the database ACL.
2. Do one of the following:
v Open a database and choose File - Database - Properties.
v As you create a new database, click the Advanced button.
3. Select or deselect properties listed in the table below.
4. After you select any of these three properties, compact the database for the property to take effect:
v Don’t maintain unread marks
v Optimize document table map
v Don’t support specialized response hierarchy

Tip: You can use the compact task with specific options to enable or disable the above three properties
and then compact the database.

Improves
To optimize database Reduces database
Property Tab performance/size performance? size?
Allow use of stored forms in this Basics Deselect option Yes Yes
database
Display images after loading Basics Select option Yes No
Don’t maintain unread marks Advanced Select option Yes Yes
Optimize document table map Advanced Select option Yes No
Don’t overwrite free space Advanced Select option Yes No
Maintain LastAccessed property Advanced Deselect option Yes No
Don’t support specialized response Advanced Select the option Yes Slightly
hierarchy
Don’t allow headline monitoring Advanced Select the option Prevents No
performance
degradation
Limit entries in $UpdatedBy fields Advanced Select the option and Yes Yes
specify the number of
entries $UpdatedBy
fields can contain
Limit entries in $Revisions fields Advanced Select the option and Yes Yes
specify a limit on the
number of entries
$Revisions fields can
contain. The
suggested limit is 10
entries.

Chapter 22. Optimizing and troubleshooting databases 453


Controlling database size
Databases whose size is monitored and minimized show increased performance: database operations
require less I/O and fewer CPU resources; view rebuilding and updating is quicker; and memory and
disk space allocation is improved. The maximum database size is 64GB on Windows and UNIX. Use the
following methods to regularly monitor the size of databases and minimize database size:
v Compact databases
v Set database size quotas to prevent databases from growing beyond a specified size
v Delete inactive documents using the document archiving tool or using agents
v Set database performance properties that also reduce database size
v Use replication settings to limit the size of a replica by replicating to it only what’s necessary
v Decrease the database purge interval to remove deletion stubs more often
v Disable the default user activity recording in databases
v Disable soft deletions in databases
For information on replication settings and the database purge interval, see the chapter ″Creating
Replicas and Scheduling Replication.″ For information on user activity recording, see the chapter
″Maintaining Databases.″

Monitoring database size


Use the following method to monitor database size and used space in a database.
1. Open the database and choose File - Database - Properties.
2. Click the Info tab (i) to see the size of the database.
3. Click % Used to display the percentage of database space in use.
For information on other methods of monitoring database size, such as the Statistics Collector task, as
well as Log Analysis and Event Monitors, see Administering the Domino System.

Compacting databases
When documents and attachments are deleted from a database, Domino tries to reuse the unused space,
rather than immediately reduce the file size. Sometimes Domino won’t be able to reuse the space or,
because of fragmentation, can’t reuse the space effectively until you compact the database.

Styles of compacting
There are three styles of compacting:
v In-place compacting with space recovery
v In-place compacting with space recovery and reduction in file size
v Copy-style compacting

In-place compacting with space recovery only


This style of compacting recovers unused space in a database but doesn’t reduce the size of the database
on disk. Databases retain the same database instance IDs (DBIIDs), so the relationship between the
compacted databases and the transaction log remains intact. Users and servers can continue to access and
edit databases during compacting. This style of compacting is useful for databases that you expect to stay
the same size or to grow in size.

When you run Compact without specifying options, Domino uses this style of compacting on all
databases enabled for transaction logging. Domino also uses this style of compacting when you use the -b
option (case sensitive) when compacting any database.

Tip: Use this compacting method the most frequently -- it is the fastest method and causes the least
system impact.

454 Application Development with Domino Designer 7


In-place compacting with space recovery and reduction in file size
This style of compacting reduces the file size of databases as well as recovers unused space in databases.
This style of compacting is somewhat slower than in-place compacting with space recovery only. This
style of compacting assigns new DBIIDs to databases, so if you use it on logged databases and you use a
certified backup utility, perform full backups of the databases shortly after compacting is complete. This
style of compacting allows users and servers to continue to access and edit databases during compacting.

When you run Compact without specifying options, Domino uses this style of compacting on databases
that aren’t enabled for transaction logging. Domino also uses this style of compacting when you use the
-B option. To optimize disk space, it’s recommended that you run Compact using the -B option on all
databases once a week or once a month.

Copy-style compacting
Copy-style compacting creates copies of databases and then deletes the original databases after
compacting completes, so extra disk space is required to make the database copies. This style of
compacting essentially creates a new database with a new database ID. If you use copy-style compacting
on logged databases (using the -c option), compacting assigns new DBIIDs, so if you use a certified
backup utility, you should perform full backups of databases shortly after compacting completes. When
you use copy-style compacting, users and servers can’t edit databases during compacting, and they can
only read databases if the -L option is used.

Domino uses copy-style compacting by default when you use an option with Compact to enable a
database property that requires a structural change to a database or when you run Compact on a
database that has a structural change pending that was initiated from the Database Properties box.
Enabling or disabling the database properties ″Optimize document table map″ and ″Don’t support
specialized response hierarchy″ require structural database changes.

The following table compares the three styles of compacting.

In place, space
In place, space recovery with file
Characteristics recovery size reduction Copy-style
Databases that use it when compact runs Logged databases with Unlogged databases Databases with
without options no pending structural with no pending pending structural
changes structural changes changes
Databases you can use it on Current release Current release Current release (need
-c)
Relative speed Fastest Medium Slowest
Users can read databases during Yes Yes No (unless -L option
compacting used)
Users can edit databases during Yes Yes No
compacting
Reduction in file size No Yes Yes
Extra disk space required No No Yes

Renaming a copy-style compacted database


Domino attempts only once to rename a database that was copy-style compacted. You can request
successive attempts by specifying the value of the Num_Compact_Rename_Retries setting in the
NOTES.INI file. Domino tries to rename until it succeeds or the number of retries is exhausted. For
example, to request that Domino try once again to rename, specify Num_Compact_Rename_Retries=1; to
request that Domino try 5 more times to rename, specify Num_Compact_Rename_Retries=5.

If you have specified a value for the Num_Compact_Rename_Retries setting, Domino waits 30 seconds
before trying to rename a database that was copy-style compacted. You can request a different amount of
Chapter 22. Optimizing and troubleshooting databases 455
time to wait by specifying the value of the Compact_Retry_Rename_Wait setting in the NOTES.INI file.
For example, to request that Domino wait 2 minutes before trying to rename a database that was
copy-style compacted, specify Compact_Retry_Rename_Wait=120.

Domino enforces the following upper limit when trying to rename a copy-style compacted database:

Num_Compact_Rename_Retries x Compact_Retry_Rename_Wait <= 60 minutes.

When to compact databases


It’s recommended that you compact databases weekly or monthly using the -B option to recover disk
space. If you use a certified backup utility, remember to run it after compacting is complete.

Also compact databases to:


v Enable or disable specific database properties -- for example, transaction logging
v Run the document archiving tool on server databases that are configured for document deletion and
archiving
v Fix corrupted databases
For information on transaction logging, see the chapter ″Transaction Logging and Recovery.″ For
information on the document archiving tool, see the topic ″Running the document archiving tool″ later
in this chapter.

Note: The Database - Sizes view of the log file (LOG.NSF), the File Statistic reports generated by the
Statistics Collector server task, and the Info tab (i tab) of the Database Properties box, all report the
percentage of used space in a database. These are often not accurate indicators of used space; therefore,
you shouldn’t use them.

Document archiving tool


Users or server administrators can copy documents in a database that meet specified criteria to an archive
database and then delete the documents from the database. When documents that meet the specified
criteria are deleted from the database, replica stubs remain so that deletions can replicate if there are
replicas of the database.

Users or administrators can archive documents based on days since the documents were last read, last
modified, and/or marked as expired. From Designer, you enable archiving and specify settings that
control what happens when a database is archived.

To enable database archiving


1. Select a database and choose Edit - Properties or right-click the database name and choose Database -
Properties.
2. In the Settings section on the Info (i) tab of the Database Properties box, select ″Archive Settings.″
3. View or edit archive settings on the Basics, Settings, or Advanced tabs of the Archive Settings dialog
box.

Archive Settings
The tool creates an archive database with the title of the source database followed by the word ″Archive″
in parentheses -- for example, ″Sales (Archive).″ By default, the archive database is stored on a client or
server within the data folder in a folder called \archive. The file name for the archive database is
a_xxxxx.nsf where xxxxx represents the first five characters in the source database file name -- for
example, a_sales.nsf. You can customize the location and file name of the archive database.

The tool can also report information about the archiving process to an archive log database with the title
Archiving Log. By default, the Archiving Log is stored on a client or server within the data folder in a

456 Application Development with Domino Designer 7


folder called \archive. The file name for the archive database is l_xxxxx.nsf where xxxxx represents the
first five characters in the source database file name -- for example, l_sales.nsf. You can customize the
location and file name of the archive log. Multiple databases can share one Archiving Log.

You can archive documents on the client or on a server.

When you archive documents on the client, you use an archive database and archive log on the client,
and you run the archiving tool from the client. When you archive documents on a server, you create the
archive database on a server rather than create it on the client. In addition, if the source database is
located on a server, you can set up server-based archiving to use the Compact task on that server to
archive the database rather than manually archive from the client. When you set up archiving, the tool
signs the archive settings with your signature; the Compact task uses the signature to verify that you
have the necessary database access to archive and then archive on your behalf. Server-based archiving
also allows you to:
v Delete documents without archiving them (the default is to archive them)
v Archive without creating an archiving log (the default is to create a log)
v Delete documents even if associated response documents haven’t been deleted (default is not to delete)

Viewing a document Archiving Log


If you set up the document archiving tool to log archiving information to an Archiving Log database, an
entry is created in the Archiving Log database when either the client or server finishes archiving. To view
this entry:
1. Open the entry in the Archiving Log database.
2. Click ″Archive statistics″ to display the date of the archive, the number of documents archived to the
Archive database, and the number of archived documents deleted from the original database.
3. Click ″Database/Server″ to display the location, title, and path for the original database and for the
Archive database.
4. Click ″Links to archived docs″ to use document links to access documents in the Archive database
that have been removed from the original database. This doesn’t apply if you selected the advanced
archiving option ″Delete matching documents without archiving them.″

Using an agent to delete and archive documents


Agents give you a very high degree of control over document deletion criteria. However, agents can be
slow to run.

The following procedure describes creating an agent using simple actions. You can also create agents
using Notes formulas, LotusScript, or Java.

When you run the agent, if Domino cannot copy all specified documents to an archive database -- for
example, if there is not enough disk space on the target folder -- the agent stops.

For more information on agents, see the chapter″Agents.″ For more information on Notes formulas,
LotusScript, and Java see Domino Designer Programming Guide, Volumes 1 through 4.

To use an agent to delete and archive documents


1. (Optional) To archive deleted documents, choose File - Database - New Copy to create a copy of the
database as the archive copy. Copy only the database design.
2. Open the database and choose Create - Design - Agent.
3. Type a name for the agent.
4. Below ″When should this agent run,″ click the arrow and select an option.
5. Below ″Which documents should it act on?″ click the arrow and select an option. Click Add Search,
specify the search criteria, then click OK.

Chapter 22. Optimizing and troubleshooting databases 457


6. (Optional) To archive deleted documents, on the bottom pane next to Run, select ″Simple action(s)″
then click ″Add Action.″ Then select ″Copy to Database″ and select the archive copy of the database
created in Step 1. Click OK and go to Step 8.
7. In the bottom pane next to Run, select ″Simple action(s)″ then click ″Add Action.″ Then select ″Delete
from Database.″
8. Close and save the agent. Then choose View - Agents, select the agent and choose Actions - Test to
simulate a run and test that it works correctly.
9. Save and close the agent if necessary.

Monitoring replication of a database


If there are replicas of a database, use any of these methods to monitor replication daily.

Method Description
Replication history Records each successful replication session for a
database. Useful for determining at a glance if a
replication is occurring.
Replication Events view of the log file (LOG.NSF) Shows details about replication events between servers.
Useful for determining the cause of replication failure
and for verifying that the expected number of replication
updates occurred.
Replication monitor Notifies you when replication of a database hasn’t
occurred within a specified time period. A server
administrator creates replication monitors as a part of
configuring the Event Monitor task.
Database analysis tool Lets you collect replication history and replication events
from the log file, and other database-specific information
into a results database that you can analyze.

In addition to ensuring that a database is replicating, you should routinely check for and consolidate
replication and save conflicts.

For information on replication monitors and the Event Monitor task, as well as the Database Analysis
tool, see Administering the Domino System.

The database replication history


In the Basics tab of the Database Properties box, there is a button ″Replication History,″ which opens the
window of the same name. The first time one server replica successfully replicates with a replica on
another server, Domino creates an entry in the replication history. The entry contains the name of the
other server, as well as the date and time of the replication. Separate entries are created when a replica
sends information and when a replica receives it. On each subsequent replication with a specific server,
Domino updates the entry in the history to reflect the most recent replication.

Domino uses the replication history to determine which documents to scan for changes during the next
replication. For example, if a database successfully replicated with the HR-E/East/Acme server 24 hours
ago, Domino replicates only those documents that were added, modified, or deleted in the replica on
HR-E/East/Acme within the last 24 hours.

Before replication starts between two databases, Domino checks the replication history of both databases
to make sure that they agree. If they don’t, Domino scans each document created or modified since the
date specified in the ″Only replicate incoming documents saved or modified after″ setting on the Other
panel of the Replication Settings dialog box.

458 Application Development with Domino Designer 7


If a database doesn’t replicate successfully, Domino doesn’t update the replication history.

To display a replication history


1. Make sure that you have Reader or higher access in the database ACL.
2. Open the database.
3. Choose File - Replication - History.
4. Click Done when you finish reviewing the history.

Tip: To copy the entire replication history to the Clipboard, click Copy.

Clearing the replication history


If you have Manager access to a database, you can clear the database replication history if you think the
database doesn’t contain all the documents it should or if the database replication history is not
synchronized with that of other replicas. Clear the replication history only as a last resort to solve
replication problems. If you clear the history, during the next replication, Domino scans each document
created or modified since the data specified in the ″Only replicate incoming documents saved or modified
after″ setting on the Other panel of the Replication Settings dialog box. If you clear the ″Only replicate
incoming documents saved or modified after″ setting, Domino scans all documents in the database.
Scanning all these documents can be time consuming, especially over dial-up connections.

Within a server cluster, the Cluster Replicator stores replication history information in memory and
updates the replication history about once an hour.

To clear a replication history


1. Make sure you have Manager access in the database ACL.
2. Open the database.
3. Choose File - Replication - History.
4. Do one of the following:
v To clear one entry, select it, click Clear, then click Yes.
v To clear the entire replication history, click Clear All, then click Yes.
5. Click Done.

For more information on the ″Only replicate incoming documents saved or modified after″ setting, see
Administering the Domino System. For information on viewing cluster replication data, see Administering
Domino Clusters.

Viewing replication events in the log file


The Replication Log entries in the Replication Events view of the log file (LOG.NSF) display detailed
information about the replication of specific databases. For each database that has replicated on a
specified server, a Replication Log shows the access the server has to the database; the number of
documents added, deleted, and modified; the size of the data exchanged; and the name of the replica that
this database replicated with. The Events section of a Replication Log shows any problems that occurred
when a specific database replicated. For example, the Events section shows if replication is disabled or if
the database ACL is preventing replication.

To use the Domino Administrator to view a Replication Log:


1. From the Domino Administrator, in the Server pane on the left, select the server that stores the log file
you want to view. To expand the pane, click the servers icon on the left.
2. Click the Server - Analysis tab.
3. Select Notes Log - Replication Events.
4. Open a recent Replication Log.

Chapter 22. Optimizing and troubleshooting databases 459


Tip: If you don’t have access to the Domino Administrator, select the log file database and choose File -
Database - Open.

Replication or save conflicts


Multiple users can simultaneously edit the same document in one copy of a database or edit the same
document in different replicas between replication sessions. When these situations occur, Domino stores
the results of one editing session in a main document and stores the results of additional editing sessions
as response documents. These response documents have the title ″Replication or Save Conflict.″ Domino
uses the $Revisions field, which tracks the date and time of each document editing session, to determine
which document becomes the main document and which documents become responses.

Replication conflicts
A replication conflict occurs when two or more users edit the same document and save the changes in
different replicas between replications. These rules determine how Domino saves the editing sessions:
v The document edited and saved the most times becomes the main document; other documents become
Replication or Save Conflict documents.
v If all of the documents are edited and saved the same number of times, the document saved most
recently becomes the main document, and the others become Replication or Save Conflict documents.
v If a document is edited in one replica but it is deleted in another replica, the deletion takes precedence,
unless the edited document is edited more than once or the editing occurs after the deletion.

Save conflicts
A save conflict occurs when two or more users open and edit the same document at the same time on the
same server, even if they’re editing different fields. When this situation occurs, the first document saved
becomes the main document. Before the second document is saved, a dialog box indicates that the user is
about to save a conflict document and if the user saves the document, it becomes a Replication or Save
Conflict document.

Note: ACL and design changes never result in replication or save conflicts; the most recent change
always prevails.

Preventing replication or save conflicts


These techniques reduce or eliminate replication or save conflicts.
v Select the Form property ″Merge replication conflicts″ to automatically merge conflicts into one
document if no fields conflict. This applies to replication conflicts only and not to save conflicts.
v Specify a Form property for versioning so that edited documents automatically become new
documents.
v Use LotusScript to write a custom conflict handler.
v Allow users to lock documents in a database.
v Assign users Author access or lower in the database ACL to prevent users from editing other users’
documents.
v If the database property ″Limit entries in $Revisions fields″ is set to a value greater than 0, increase the
limit by specifying a greater value than the existing one or specify -1 to remove the limit.
v Work with the server administrator to keep the number of replicas to a minimum.
For information on using LotusScript, see the Domino Designer Programming Guide.

Consolidating replication or save conflicts


Regularly look for and consolidate replication or save conflicts. To consolidate a conflict, merge
information into one document and remove the other document. Conflicts are easiest to consolidate
immediately after they occur, since the conflict document is still closely synchronized with the
information in the main document. It’s important to consolidate replication or save conflicts quickly, so
users access the correct information.

460 Application Development with Domino Designer 7


Tip: To locate replication or save conflicts, create a view that displays only conflict documents. Then, to
see a conflict document in context with its main document, select the Replication or Save Conflict
document in the view that displays conflicts, hold down the CTRL key, and switch to the view that
shows the main document.

For information on creating a view that displays only conflict documents, see the chapter ″Designing
Views.″

To consolidate replication or save conflicts, you can save the main document or save the Replication or
Save Conflict document.

To save the main document


1. Copy any information you want to save from the Replication or Save Conflict document into the main
document.
2. Delete the conflict document.

To save the Replication or Save Conflict document


1. Do one of the following:
v Copy any information you want to save from the main document into the Replication or Save
Conflict document.
v If you do not need to save any information from the main document, perform a minor edit in the
Replication or Save Conflict document -- for example, delete a space. This will allow you to save
this document as a main document.
2. Save the conflict document. The conflict document becomes a main document.
3. Delete the original main document.

Monitoring database activity


Monitor database activity regularly. If database activity is high and users report performance problems,
do any of the following:
v Set database properties that improve performance.
v Create a replica of the database on another server, if possible, one within a server cluster.
v Move the database to a more powerful server.
v Move the database to a disk that is less heavily used, or if it’s a large database, to its own disk.

Consider deleting an inactive database or view to free disk space on the server.

How the Statlog task generates activity statistics


The Statlog task runs by default once a day at 5 AM to report database activity on the server. The
information appears as Database Activity Log entries in the Database - Usage and Database - Sizes views
of the log file (LOG.NSF) and in the User Activity dialog box of individual databases. The Statlog task
also reports database size statistics in the Database - Sizes view of the log file.

Chapter 22. Optimizing and troubleshooting databases 461


This table compares the information generated in each location.

Appears in Database
Information provided Activity Log entries Appears in User Activity dialog box
Total number of times user and Yes Yes
servers accessed, read, and wrote to a
database in past 24 hours, past week,
past month, and since the creation of
the database.

Includes activity for anonymous and


authenticated Internet clients.
Inactive views (indicated by the size Yes No
0)
Names of users and servers who read No Yes
and wrote documents, sorted by date.

Includes activity for anonymous and


authenticated Internet clients.

Tip: In addition to viewing activity statistics reported by Statlog, you can evaluate database activity by
creating a view that sorts documents by date. You can also create File Monitor documents as part of
Event Monitor configuration. File Monitors report user activity for specific databases.

For information on File Monitor documents, the Event Monitor task, and monitoring Web site activity, see
Administering the Domino System. For information on monitoring Web site activity, see Administering the
Domino System. For information on monitoring database activity within a server cluster, see Administering
Domino Clusters.

Viewing database activity statistics generated by the Statlog task


Checking database activity statistics allows you to resolve or avoid problems with an application.

In the log file (LOG.NSF)


1. From the Domino Administrator, in the server pane on the left, select the server that stores the log file
you want to view.
2. Click the Server - Analysis tab.
3. Do one of the following:
v Select Notes Log - Database - Sizes.
v Select Notes Log - Database - Usage.
4. Double-click a Database Activity Log entry to view it.

Tip: If you don’t have access to the Domino Administrator, select the log file database and choose File -
Database - Open.

In the User Activity dialog box


1. Open the database and choose File - Database - Properties.
2. Click the Info tab (i), and then click ″User Detail.″

Tip: To track usage over a period of time, choose ″Copy to Clipboard″ to copy the summary to a
document that you use to track usage statistics.

462 Application Development with Domino Designer 7


Managing database activity recording in databases
By default, the Statlog task reports database activity to all database User Activity dialog boxes when it
runs. Even if a user disables User Activity reporting for a specific database, the next time Statlog runs, it
enables recording in the dialog box again.

To disable automatic activity recording in User Activity dialog boxes


To prevent Statlog from automatically recording activity in User Activity dialog boxes, add the following
setting to the Notes.ini file:
No_Force_Activity_Logging=1

Then, you can enable activity recording per database, as needed. Since recording activity in the User
Activity dialog box adds 64K to the size of each database, disabling automatic activity recording saves
disk space on the server.

Note: If you use No_Force_Activity_Logging, Statlog still reports activity to the log file (LOG.NSF).

To enable activity recording in a single database’s User Activity dialog box


Even if the server administrator disables automatic activity recording in databases, you can enable
recording for a single database.
1. Make sure that you have Designer or Manager access in the database ACL.
2. Open the database and choose File - Database - Properties.
3. Select the Info(i) tab, and then click ″User Detail.″
4. Select ″Record Activity″ to enable activity recording.
5. (Optional) Select ″Activity is Confidential″ to allow only users with at least Designer access in the
database ACL to view the activity.
6. Click OK.

To disable activity recording in a single database’s User Activity dialog box


Disabling activity recording also removes any existing activity statistics in the User Activity dialog box.
1. Make sure that you have Designer or Manager access in the database ACL.
2. Open the database and choose File - Database - Properties.
3. Select the Info tab (i), and then click User Detail.
4. Deselect ″Record Activity″ to disable activity recording.
5. Click OK.

Updating database indexes and views


A view index is an internal filing system that Notes uses to build the list of documents to display in a
database view or folder. View indexes should be kept current so that information in views and folders
stays synchronized with document updates.

A full-text index is an index of the text in a database. To perform advanced searches for text in a
database, users need an up-to-date full-text index that reflects the latest content of a database.

You can use any of the following to update database indexes:


v The Update task
v The Updall task
v Keyboard shortcuts
v The Full-text tab of the Database Properties box

For information on creating and deleting indexes, see Lotus Notes Help. For information on purging or
deleting view indexes with the Update and Updall tasks, see Administering the Domino System.

Chapter 22. Optimizing and troubleshooting databases 463


Notifying users of a moved database
After you move a database, create a new database with the same file name and path as the database
before you moved it. In the new database, create a form and document that provides the following
information:
v Title of the original database
v File name and path of the original database
v Date of the move
v Reason for the move
v Server currently storing the database
v New file name and path of the database

When users open this database, they’ll see information about the new location.

Adding a button to open a database


In addition to including information about the database move in the form, you can create and program a
button that users click to automatically add and open the database at its new location.

For example, this button formula adds a database with the replica ID 84254E66:0064508 to the workspace
and then opens the database:
@Command([FileOpenDBRepID];"84254E66:0064508"; "SALES")

The last argument, ″SALES,″ provides the name of the server on which the database is located.

Troubleshooting database performance


You can reduce database performance problems by using:
v Transaction-based logging and recovery.
v Disk-tuning procedures, such as disk defragmentation and disk-space reallocation.

The following topics suggest solutions to common database performance. Some of the recommended
solutions involve changing the database design. You should always test design changes on a template or
a copy of the database before applying them to the production copy.

For more information on transaction logging, see Administering the Domino System.

The topics in this section include:


v Users cannot access the database
v Users experience a delay when accessing the database
v Using Find Note to analyze a document reported in the log file
v Troubleshooting replication problems

Users cannot access the database


Users may not be able to access databases for the following reasons.

The server storing the database is temporarily down


Check with the Domino administrator and tell users that when the database is expected to be available
again.

464 Application Development with Domino Designer 7


Users don’t have the appropriate access
Check the database access control list (ACL) to make sure that users have the necessary access to the
database. Check with the Domino administrator to ensure that users have access to the Domino server
that stores the database.

Server backup is occurring during work hours


Users may be unable to access a server that is being backed up during work hours because a full backup
may require significant disk I/O capacity. Ask the Domino administrator to schedule backups to occur
overnight, if possible.

Use a Domino 6-compliant backup program so users can access databases on a server that is being
backed up. Users can make changes to databases as a backup occurs because Domino provides a
point-in-time image of the database, beginning with the time the database backup starts.

The server is continuously updating a full-text index


If a database is large and active, database performance can be slow if the server updates a full-text index
too frequently. Change the full-text index update frequency if necessary.

For more information on update frequency, see Administering the Domino System.

Users experience a delay when accessing the database


Users may experience a delay when accessing databases for the following reasons:

The database is heavily used


View the User Activity dialog box to see if the database is heavily used. This option is on the Information
tab of the Database Properties box. Check the server to see if its hardware and memory are powerful
enough to support the user activity for the database. If the server is not powerful enough, you may need
to upgrade hardware or memory on the server. You can also create an additional replica of the database
so all users are not always using the same one. If disk contention is a problem, move the database to a
less heavily used disk.

There are too many views


If the database contains many views, consider consolidating some of them. For example, you can
consolidate views by creating alternative collations in the same view, rather than using separate views.
Database performance can suffer when a database contains many views.

View indexes are being refreshed too frequently


If the database is heavily used or contains many documents, refresh view indexes less frequently, if
possible.

Unread mark processing may cause delays


Delays can occur as the unread marks in a database are updated while the database is opening. It also
creates disk contention, which slows down every operation on the database. Disabling unread marks on
the database eliminates the delay.

The database design is complex


A complex database design can cause performance problems. Consider simplifying the database design.

Database performance properties are not being used


If feasible, set database properties to improve database performance.

The database cache needs adjustment


If you are a system administrator, monitor the database cache on the server that stores the database to see
if it’s working effectively. If necessary, increase the number of the databases the cache can hold. The NSF
buffer pool size may also need to be increased.

Chapter 22. Optimizing and troubleshooting databases 465


Using Find Note to analyze a document reported in the log file
You can use the Find Note dialog box in the Domino Administrator to analyze a document reported in
the log file. If the log file reports a problem with a document, you can display the properties for the
document to help you to troubleshoot the problem. For example, you can use Find Note to review the
document properties for a document that cannot replicate.
1. Copy or write down the hexadecimal Note ID (for example, NT201B2) of the documentreported in the
log file to the Clipboard. You may also troubleshoot using the universal Note ID (UNID), a unique
identifier used to locate the same document across database replicas.
2. In the Server list, select the server that stores the database that contains the reported document.
3. Click the Files tab and select the database that stores the reported document.
4. Choose Tools - Database - Find Note.
5. Select one:
v by Note ID
v by Universal Note ID (UNID)
6. Paste or enter the Note ID or UNID from Step 1 into the ID field.
7. Click Find.
8. View the document details and properties in the Fields and Properties fields.
For more information about determining the Notes ID for a document, see the chapter ″Completing
an Application and Managing Design Changes.″

Troubleshooting replication problems


The following topics suggest solutions to common problems associated with scheduled replications.
v A database replica database does not contain all the documents it should
v A database replica is not receiving design changes
v Changes to the database title do not replicate
v Database replicas are different sizes
v The database stops replicating and the option ″Enforce a consistent ACL″ is selected
v The database replica has not received ACL changes
v The new replica contains the ACL of the source server but you did not copy the ACL
v You see the message ″Database is not fully initialized yet″
v Deletions are not replicating
v Unexpected deletions occur in a replica
v Deleted documents reappear

For cluster replication problems within a server cluster, consult with your Domino administrator. The log
file (LOG.NSF) provides helpful information for troubleshooting replication problems within a cluster,
and your administrator can help you assess the operation of your cluster.

For more information about replication and server clusters, see Administering Domino Clusters.

A database replica does not contain all the documents it should


If none of the following explanations apply, clear the replication history by using the File - Replication -
History dialog box in the Notes client.

Replicas are different sizes


If changes made to one replica have not yet replicated, the content of replicas may be different until
replication occurs.

466 Application Development with Domino Designer 7


The source server has insufficient access
The source server access in a destination replica ACL determines what the destination replica can receive
from the source server. Give the source server higher access in the destination replica ACL if necessary.
The following message in the server log (LOG.NSF) indicates insufficient server access:
Access control is set to not allow replication

There is no destination server in an access list


Access lists allow only a subset of people and servers in the ACL to access documents. If such access lists
exist, add the destination server to them in the source server replica. If the access list uses a role to define
access, add the destination server to the role on the source server replica.

An intermediate server has insufficient access


If replication between a source and destination server occurs through an intermediate server, make sure
the source and destination server replica ACLs give the intermediate server high enough access to
replicate all changes.

Replication settings are filtering documents


Some replication settings act as filters that screen out documents and features. Check the replication
settings.

The server is out of disk space


If the database is a Release 4 format database, check to see if it exceeded the maximum database size.
Ask your Domino administrator to resolve disk space problems and if necessary, consider moving a
replica to another server or deleting databases on the server.

Older documents weren’t replicated to a new replica


Change the date specified for the replication setting option ″Only replicate incoming documents saved or
modified after.″ To view the date, choose File - Replication - Settings and click the ″Other″ tab in the
Notes client. Create a new replica and specify an earlier date.

A database replica is not receiving design changes


To receive design changes from a source server, the database replica on the destination server must give
the source server at least Designer access and the source server replica must give the destination server at
least Reader access.

Changes to the database title do not replicate


If the replication setting ″Do not send changes in database title & catalog info to other replicas″ is
selected on the source server replica, the title won’t replicate. Deselect this setting to replicate a database
title. To view this setting, choose File - Replication - Settings and click the ″Send″ tab in the Notes client.

Database replicas are different sizes


Database replicas may be different sizes for the following reasons:

Replication settings
Some replication settings cause one replica to receive only a subset of documents and features from
another replica.

Access Control List


The ACL prevents a replica from receiving all documents or design elements from a source server replica.

Read ACL or Reader Names fields


A destination server isn’t included in a Read ACL or Reader Names field and therefore doesn’t receive all
documents from a source server replica.

Chapter 22. Optimizing and troubleshooting databases 467


View indexes
A view is used in one replica but not in another, and the replica containing the unused view is smaller
because no index is built for the unused view.

Private agents or personal views or folders


If these features are used on one replica, but not on another, there can be a size disparity between the
replicas.

Deletions are not replicated


Check these replication settings by choosing File - Replication - Settings in the Notes client:
v On the Advanced panel, make sure that the Deletions option under ″Replicate incoming″ is not
selected.
v On the Send panel, make sure that the ″Do not send deletions made in this replica to other replicas″
option is selected.

Unused space
One replica has been compacted while another has not been compacted.

The database stops replicating


If a user changes a local or remote server database replica’s ACL when the ″Enforce a consistent access
control list across all replicas of this database″ option is selected, the database stops replicating. This
option is found on the Advanced panel of the Access Control List dialog box. The message in the log file
is:
Replication cannot proceed because cannot maintain uniform access control list on replicas

The database replica has not received ACL changes


To receive ACL changes from a source server, the database replica on the destination server must give the
source server Manager access and the source server must give the destination server at least Reader
access.

The new replica contains the ACL of the source server but you did not
copy the ACL
A replica stub is an empty replica that has not yet been populated with documents. When you choose
File - Replication - New Replica, Notes creates a replica stub and populates it with documents, either
immediately or at the next scheduled replication, depending on the option you select.

Somebody modified the access control list on the source server before initial
replication occurred
If you create a replica stub and somebody modifies the ACL on the source server before initial replication
occurs, the ACL on the source server becomes the most recent one and replicates to the replica stub.
Simply opening the Access Control List dialog box on the source server replica and then closing it can
cause this problem.

The server times are not synchronized


If you create a complete replica immediately (rather than creating a replica stub) and the time on the
source server is later than the time on the destination server, the new replica contains the ACL from the
source server.

You see the message ″Database is not fully initialized yet″


A replica stub on a workstation hasn’t been manually replicated
If users create replica stubs on their workstations and don’t populate them with documents according to
a schedule, they must manually replicate to populate the database replica with documents.

468 Application Development with Domino Designer 7


The server storing the replica stub doesn’t have adequate access to pull
information
If you rely on scheduled replication to populate a replica stub, the server storing the replica stub must
have at least Reader access in the source server replica ACL to pull the documents from the source server.

An appropriate Connection document between two servers isn’t in place


If you rely on scheduled replication to populate a replica stub on a server with documents from a replica
on another server, a Connection document must exist between the two servers storing the replica and the
replica stub. Confirm with your Domino administrator that a Connection document exists and that it is
configured correctly.

Replication is disabled
Notes cannot populate a replica stub if replication is disabled on the source or destination server replica.
To see if replication is disabled for the database, see if the ″Temporarily disable replication″ option is
deselected. This option is found on the ″Other″ tab when you choose File - Replication - Settings in the
Notes client.

Deletions are not replicating


Servers don’t have adequate access to the database
To receive document deletions, the ACL on a destination server replica must give the source server Editor
access or higher and have the access level privilege ″Delete documents″ selected.

A replication setting is preventing deletions from replicating


Review these replication settings by choosing File - Replication - Settings in the Notes client:
v On the Send panel, if the option ″Do not send deletions made in this replica to other replicas″ is
selected, a source server doesn’t send deletions to another replica.
v On the Advanced panel, if the Deletions option under ″Replicate incoming″ is not selected, a replica
doesn’t receive deletions.

Unexpected deletions occur in a replica


Check these replication settings by choosing File - Replication - Settings in the Notes client:
v On the Advanced panel, deselect ″Replicate incoming: Deletions″ to prevent a database from receiving
deletions made in other replicas.
v On the Other panel, select ″Do not send deletions made in this replica to other replicas″ to prevent a
database from sending deletions.

Unexpected deletions may also occur for the following reasons.

There is a new replication formula in place


A new replication formula overrides previous formulas and removes documents that don’t match the
formula.

A replication setting is automatically removing older, unmodified documents


The replication setting ″Remove documents not modified in the last [ ] days″ removes older, unmodified
documents. If the specified number of days is low, consider increasing the value. This option is on the
Space Saver panel when you choose File - Replication - Settings dialog box in the Notes client.

Deleted documents reappear


A purge interval prevents replication of deletions
When a document is deleted, it leaves behind a deletion stub. When the database replicates, Notes uses
the deletion stub to identify and delete the same document in the replica.

Chapter 22. Optimizing and troubleshooting databases 469


To save disk space, Notes purges deletion stubs according to the replication setting ″Remove documents
not modified in the last [ ] days.″ If Notes purges the deletion stubs before they replicate, deleted
documents can reappear after the next replication. This option is on the Space Saver panel when you
choose File - Replication - Settings in the Notes client.

A document edit writes over a document deletion


v When the same document is modified on different servers between replication sessions, the document
that was modified most frequently takes precedence. If both documents are modified only once, the
one modified most recently takes precedence.
v If a document is edited multiple times on one server and deleted on another server between replication
sessions, the edited document takes precedence because it underwent the greatest number of changes,
even if the deletion was the most recent change.
v If somebody deletes a document on one server and then someone else updates the document on
another server once between replication sessions, the edit overrides the deletion because both
documents were updated once and the edit occurred after the deletion.

470 Application Development with Domino Designer 7


Chapter 23. DB2 Access views
Domino Designer 7 includes two new types of design elements to assist you in managing data contained
in DB2 enabled Notes databases:
v DB2 Access view (DAV) - a shared resource that lets you define a DB2 view of Notes data.
v Query view - another type of NSF view, this view is populated by using the SQL language queries. If
you want to create a query view based on data in a Notes database that resides in DB2, you must first
have defined and populated a DAV.

A Notes database typically includes many different types of notes. When you enable a Domino server for
DB2, Domino stores its Notes data in DB2. A DB2 database consists of multiple tables that are composed
of columns and rows. Data in DB2 databases is accessed and manipulated through Structured Query
Language (SQL) statements.

When a Notes database is enabled for DB2, Domino creates a DB2 database schema for it, as well as a set
of tables in that schema to hold the Notes database data. The schema name is based on the NSF file
name. Any DAVs you create will also be located in this schema.

Including all of the notes in an NSF in a single DB2 table would not be effective for SQL access, because
a set of notes does not typically have a uniform set of fields (or columns, in a DB2 database) and
therefore would probably not be able to be grouped in ways that make sense for SQL queries. To make
SQL access useful and manageable, you must define DB2 views that specify the columns you want to
access via SQL, and the notes that belong in this view (which constitute the rows of the view).

You define and manage these DB2 views of your data using a design element called the DB2 Access view
(DAV). The DAV is a shared resource that enables Notes designers to create views of data in DB2 enabled
Notes databases. While the DAV actually exists in DB2, it is accessible by both Domino and non-Domino
applications.

You do the following to define a DAV:


v Define the columns in the DB2 view. You can do this manually by inserting fields in the DAV
definition and setting the field attributes (column name, DB2 data type, matching Notes data type, and
so on), or you can choose fields from existing forms and subforms. In this case, Designer will create a
suitable column definition in DB2, which you can then modify to suit your needs.
v Define the row selection criteria. This defines which notes in the NSF should be visible in the DB2
view. For Notes 7.0, this can be notes created from a specific form, notes created from a specified set of
forms, or all notes in the NSF.
v Set the DAV properties. These control the DAV behavior; for example, whether notes inserted using
SQL perform a ″Compute with form″ operation to generate computed fields on the note.

For example, suppose you have an NSF that contains mailing list information for several different groups,
and you want to consolidate information for three of those mailing lists: PTA, Book group, and
Playground fund raiser. These mailing lists (forms) all contain the same basic information -- name,
address, city, zip -- as well as some other information specific to each activity.

When you create a DAV for this NSF data, you select the four address fields from the ’PTA’ form to
define the columns in DB2. (As these fields are the same on all forms, it does not matter which form you
use to create the column definitions.)

Next, you select which notes you want to appear in the DB2 view by selecting all three of these forms.

471
After the DAV is successfully created, you will be able to query the consolidated mailing list in DB2. This
DB2 view would contain the four specified columns for all the notes created with the selected forms.
Other fields on the selected notes would not be visible in DB2 because they are not part of the view
column specification. For example, phone numbers would not be visible in DB2 because the phone
number field was not selected as a column definition. Furthermore, notes created with other forms would
not appear in the view because they are not part of the views row selection criteria. For example, notes
created from the mailing list form ’Holiday cards’ would not appear in the DAV.

Once the DAV is created, any subsequent changes made to the Notes data will immediately be visible in
DB2. Any changes to the notes made using SQL will immediately be visible in Notes (you may need to
refresh the Notes view to see change in the Notes client).

Note: The size of a DAV and its entities (tables, views, triggers, and indexes) are not included in the total
file size of the DB2 enabled Notes database for which it was created. Therefore, if you have numerous
DAVs associated with a DB2 enabled Notes database, be aware that they occupy disk space above and
beyond that of the DB2 enabled Notes database.

Prerequisites for working with Notes databases that reside in DB2


In order to work with DB2 enabled databases, your Domino administrator should have set up your
environment as follows:
v You must have successfully DB2 enabled a Domino server.
v DB2 Access for Lotus Domino should be installed on the same machine as the DB2 server that hosts
Notes data. This might be the same computer as that on which Domino is installed (″local″
configuration), or a different computer (″remote″ configuration). DB2 Access for Lotus Domino acts as
an extension to DB2 and enforces Notes database security (such as ACLs and reader lists) for DB2
enabled data. If DB2 Access for Lotus Domino is not installed properly, the DB2 Designer functions
will not be available and you will not be able to access DB2 using SQL.
v In order to run any query views, Notes data or federated data, You need a DB2 OS account name in
addition to your Notes user ID. These IDs must be linked in the Domino Directory via a DB2 account
name in your Person document (Administration tab). This maps your Notes ID to a DAV or QV. Have
the Domino Administrator use the ″Set DB2 user name″ tool in the IBM Domino Administrator Client
to set this field.
v The NSFs on which you will be working should have been migrated to DB2. Only NSFs that are stored
in DB2 can be accessed using SQL. If you have existing NSFs that you would like to migrate to DB2,
you can do so by making a new copy or a new replica to a DB2 enabled Domino server.
v The only file type stored in DB2 is an NSF. DAVs and QVs are supported only in DB2 enabled
databases; for example, templates cannot contain DAVs.

DAV security
It is important to note that even though DAVs exist in DB2, Domino still manages user access to them.
The ability to read Domino data from DB2 is enforced with the same basic security as that for using the
NSF itself. Therefore, in order to access a DAV through DB2, the DB2 user’s associated Notes ID must:
v Have access to the Domino server on which the DB2 enabled Notes database resides.
v Have access to the DB2 enabled Notes database.
v Have proper Notes Access Control List (ACL) permissions to perform the requested operation. For
example, the user must have Reader access or higher to issue a SELECT against the DAV, and they
must have Author or Depositor access to INSERT into the DAV
v Be included in the reader lists of the specific notes that are included in the DAV.

472 Application Development with Domino Designer 7


Note: Because notes in NSFs translate to rows in DB2 enabled Notes databases, Domino essentially adds
row level security to DB2 data through the use of reader lists. If two different users perform a select on a
DAV (SELECT * from test.dav), they might get different numbers of rows returned, depending on the
notes to which they have read access

Furthermore, the following must be true in order for either a Designer or DB2 user to access DAVs:
v The Domino server on which the DB2 enabled NSF resides must be up and running.
v The user who is trying to access this data must have both a DB2 OS account name ID (to use in the
SQL connect statement) and a Notes User ID.
v In order to run any query views, Notes data or federated data, You need a DB2 OS account name in
addition to your Notes user ID. These IDs must be linked in the Domino Directory via a DB2 account
name in your Person document (Administration tab). This maps your Notes ID to a DAV or QV. Have
the Domino Administrator use the ″Set DB2 user name″ tool in the IBM Domino Administrator Client
to set this field.
v The DB2 user must have access to the DAV itself (this is the default when the DAV is created in
Designer)

Creating a DAV
1. In Domino Designer, open the Notes database that resides in DB2 for which you want to create a
DAV.
2. Select Create - Design - DB2 Access View.
3. Specify the fields (columns) to use in the DAV. Choose one of these options:
Choose Field -- to chose from existing design elements.
a. In the Type field, select the design element to be used as a field source, or choose All. All
instances of the chosen field selection source now appear in the left-hand list box.
b. Select fields for inclusion in the DAV by highlighting a field source. The fields appear in the
right-hand list box.
c. Select all the fields that you want to include in the DAV.
d. Repeat for each field selection source, as required.
Insert Field -- To add a blank field to the DAV in which you can type an existing field name or the
name of one that will be added to a form associated with the DAV.
4. Set the properties for each field by double-clicking on the field and completing the Access View
Entry dialog box:

Field Action
Field name Enter the field name if adding a new field.

This is the matching field name for the DB2 column in the DAV, so it must be the
actual name of a field that appears in the note (otherwise no matching field would be
found and the column in the DB2 view would be blank)
Note: If you used the Choose Field method of specifying the fields for the DAV, you
will be able to edit the field names in the properties, but if you change the field name
so that it no longer matches a field name in the note, the corresponding column in the
DB2 will be blank.
Notes type Indicate the Notes data type for this field
Note: Formula, rich text, and rich text light Notes data types are not supported for use
in DAVs.
DB2 type Indicate the DB2 data type for this field. Notes will indicate a default value associated
with the Notes type you choose.
Note: If you have an integer defined in the DAV, and an insert from DB2 supplies a
real number (with a decimal), the insert will succeed and the decimal value will be
truncated.

Chapter 23. DB2 Access views 473


Field Action
DB2 index field Creates this column as a DB2 index field, which keys the database record for rapid
retrieval
Allow truncation of Notes Specifies that the DB2 view can ″clip″ the notes data (only show DB2 column length
data characters)
Store multiple values If a Notes field has multiple values, you can select to use:
v first value in the field only
Note: this option is enabled
only for multi-value fields. v delimited values. For multi-value fields, all of the data values can appear in the
view as delimited text.
DB2 multi-value delimiter If you have chosen to use delimited values in this field, indicate the delimiter used.

This delimiter is the one that will be used to separate multiple values in the DB2
column and the delimiter that will be used to parse DB2 INSERT or UPDATES into
separate values. It is not related to the delimiter specified in the form design that is
used by the Notes client.

The default is a semicolon.


DB2 column length This is used to define the column length in DB2 (essentially field length in Notes).

This is only required for columns mapped to the DB2 Varchar data type (all other
types are fixed length). The default for varchar is 100.

Note: You can change the order of the fields in the view by dragging and dropping them. For
example, you may want to position frequently accessed fields at the beginning of the view.
5. Click Design - DB2 Access Views to specify the properties for the DAV itself. In the DB2 Access View
dialog, complete the following:

Field Action
Name Enter a name for the DAV. This is the actual name of the DB2 view and must be a valid
DB2 view name. If you enter spaces in the name, they will be converted to underscores in
DB2 (e.g. zip code becomes zip_code).
Comment Enter information about the DAV
Select the form(s) Specify the row selection criteria by doing one of the following:
associated with this v Select all forms to associate all forms in the database with the DAV. All data notes in the
DB2 Access view NSF will have a row in the access view.
v Select individual forms from the list box to associate with the DAV. This list is used by
DB2 to determine the data with which to populate the DAV. Only data notes with a
FORM item matching one of the selected values will be in the view.

6. Specify options for adding data to the DAV from DB2:

Field Action
Compute with form on DB2 insert or update Enable this option if the selected form(s) contain computed
fields and you want the formulas to be computed when the
note is created or updated using SQL.
Default form to use for DB2 inserts DB2 users can perform inserts, updates, and deletes (given
the right permissions) against data in the DAV. However,
you can only perform these operations against one form
associated in the DAV definition, even if multiple forms are
selected. Specify the form that will be used for DB2 inserts,
updates, and deletes.

474 Application Development with Domino Designer 7


7. Specify DAV options on the Advanced tab:

Field Action
Include UNID in access view Select to have the Notes UNID for each field appear in the
DAV.
Include OID in access view Select to have the OID for each note appear in the DAV. If
SELECTed in the Query View’s SQL formula, allows
document links to work when notes are selected and
copied as a table.
Include modified time in access view Select this option to include the Notes modified time for
each note in the DAV. Note that this timestamp is
modified to GMT.
Normalize to GMT for time zone conversions Select this option to standardize all dates and times in the
DB2 view to GMT. This is especially useful for distributed
DB2 applications that are accessed by users in different
time zones.

8. Save the view.


9. (Optional - recommended) Click Validate. Validating the DAV verifies that the definition meets the
minimum requirements to build a valid DB2 view and gives you a quick way to check the validity
of the Access View definition while you are still in the DAV designer.
10. Close the view.
11. In the DAV work pane, click Create/Update in DB2.
12. Click Populate in DB2. This populates the view with the field data.

Notes:

The Populate task is an asynchronous server task. No notification of task progress is provided. Click
Refresh List to check on the task status.

Populating a DAV against a large data set can be time consuming and contribute to server load. If you
have created a DAV for a large database, consider populating the view during off hours.

Populating the view is a one-time event. After the view has been populated, it is kept in sync with
normal Note updates and DB2 updates.

Viewing the status of your DAV


The following icons show the status of the DAV you are creating:

New DAV, not yet created or populated in DB2


New DAV that has been created in DB2 (but not yet populated)

DAV has been successfully created and populated in DB2

There is an error in the DAV

Managing DAVs
Once you have created a DAV, you can use Designer to edit the dav definition, or DB2 or Notes to act on
data it contains.

Chapter 23. DB2 Access views 475


In Designer
To work with an existing DAV, in the Design pane for this database, click Shared Resources > DB2 Access
View. A list of all DAVs created for this database appears. Select and double-click the one you want to
edit. From this work pane, you can do the following:
v New DB2 view - create a new DAV
v Create/update in DB2 - create/update the DAV in the DB2 enabled database
v Populate in DB2 - add data to the DAV
v Delete in DB2 - delete the DB2 view that was created using the DAV
v Refresh list - refresh the list of DAVs in the work pane. This is useful for checking the status of DAVs
in DB2.

In DB2
If you know the NSF file name (e.g. test.nsf), you can find the schema name by executing the query:
SELECT NSFSCHEMA from DOMINO.CATALOG where filepath=’test.nsf’

where DOMINO is the master Domino schema (this is defined at installation, so check with your
administrator if this name is not found) and the file path is the name of the file relative to the Domino
data directory. The file path name must be lower case.

Note: If you are unable to execute this query , you may need to ask your administrator to grant you
READ access to the table in DB2.

Any DAVs that you create will also be located in the NSF schema. So, in the above example, if you create
a DAV named ’mydav’, you would access it in SQL like this:
SELECT * from test.mydav

DB2 are optimized for read access ( SQL SELECTS ). While SELECTS do require the owning Domino
server to be available, almost all of the processing, including reader list processing, is done by DB2 (in
the DB2 process space).

INSERTS, UPDATES, and DELETES are not done by DB2 directly. They are sent as requests to the
Domino server and handled by Domino. This is necessary to ensure the correct synchronization of these
events in Domino (for example, conflict document handling). It is important to note that because of this,
SQL operations in DB2 are handled in an autocommit fashion. An important implication for inserts,
updates, and deletes that you need to consider if you write SQL applications to manage Notes data is
that SQL statements that affect multiple rows (for example, updating all members of department 80 to
department 99) update each row independently.

This restriction does not apply to SELECT statements.

Troubleshooting DAVs

ACLs needed for DAVs


When using DAVs, if users encounter problems while attempting to access your DB2 enabled Notes
database, make sure that the ACL entry for each user is identical to the first entry in the ″User Name″
field in that user’s Person document in the Domino Directory on the Domino server.

Errors using the Select statement


If you attempt to select from the Access View via a select statement in a DB2 Command Line Processor
window and get the following error, contact your administrator.

476 Application Development with Domino Designer 7


SQL0443N Routine "ISREADER" (specific name "") has returned an error
SQLSTATE with diagnostic text "The server is not responding. The server
may be down or you ". SQLSTATE=04004

You can also troubleshoot this error using information in the topic about resolving errors when using
SELECT, if you have installed the Lotus Domino Administrator Help. Go to
http://www.lotus.com/ldd/doc to download or view Lotus Domino Administrator Help.

Exporting TIMEDATES to DAVs


The Notes TIMEDATE can store the date, the time, the time zone, and a daylight savings time indicator,
but a DB2 timestamp only stores the date and time. DB2 assumes that all dates and times are local to the
DB2 server’s timezone. This can cause the incorrect time to display when exporting TIMEDATEs to
DAVs, or reading TIMESTAMPS from DB2 in a query view (whether they are from DAVs or other DB2
tables).

There are two options for saving the date and time in DAVs -- local time or modified to GMT
(standardized). You choose the way you want them handled using the advance tab on the ″Access View
Entry″ properties page, and then set the ″Normalize to GMT for time zone conversions″ field accordingly.

Note: You must rebuild your DAV if you change this setting for an existing DAV.

Inserting date ranges in a DAV


When inserting or updating date ranges in a Note inside of a DAV via SQL, you must specify the date
ranges with the full DB2 timestamp, such as yyyy-mm-dd-hh.mm.ss.subsec or 2005-12-12-08.06.30.123456.
Failure to do so will result in the value being inserted as a null.

Unknown host error


If you ping the Domino server by name and get an ″unknown host″ error, it may indicate that the
network address of the server is not a fully qualified DNS name or IP address.

Updatable cursors do not work


Updates to a DB2 Access View through the DB2 Control Center do not work. You can perform these
functions only through the DB2 Command Line Processor or DB2 Command Window. This is because in
Domino and DB2, updatable cursors do not work with ″Instead of″ triggers.

Using GMT TimeDates with Query Views based on DAVs


Query views use only the value in DB2, they do not interpret it or adjust it. You can see the query result
in local time by adding the DB2 time zone into the query and using a column formula to adjust the time.
For example:
"select textcol, (CURRENT_TIMEZONE/10000) as ctz, dtcol from dt.dt"

and then use a column formula to adjust the value shown to the user:
@Adjust(dt;0;0;0;CTZ;0;0)

You could get the same results by adjusting the returned timestamp using the information from @Zone:
@Adjust(dtcol;0;0;0;-@If(@Zone - @Integer( @Zone )
> 0.05;@Integer(@Zone)-1;@integer(@Zone));0;0)

Where dtcol is the selected TIMESTAMP column in DB2.

Note that a production formula may need to be a little more robust because @Zone can return an hhmm
value if the server’s time zone is not a whole hour multiple away from GMT.

Chapter 23. DB2 Access views 477


Although this approximates a normal Notes view, there are a few inconsistencies. For example, this
shows the time correctly relative to the GMT, but it displays the date and time values relative to the DST
value in the date (that is, it shows whether DST was in effect on that date or not), whereas the formula
method shows the time relative to the current DST setting.

478 Application Development with Domino Designer 7


Appendix A. Domino Designer templates
The templates described in the following table are available with Lotus Domino Designer and are
specifically intended for use by application developers.

For information on system administration templates, see the topic ″Application and System Templates″
found in Administering the Domino System or in the Lotus Domino Administrator Help.

Table of Domino Designer templates


If you install the templates with Lotus Domino Designer 7, you’ll find them in the Notes data directory.

In the table, an asterisk (*) indicates that additional information on this template appears in the Domino
Designer Templates Guide available on the Lotus Developer Domain Web site:
http://www.lotus.com/ldd/doc.

File name & design


Database title template name Audience Description
Discussion - Notes & discsw7.ntf Notes and Web Electronic conference room.
Web (7) (*) users
StdR6Disc Features: Threaded discussion database with
user profiles that allow users to receive
automatic mailing with links to items of
interest. Anonymous responses, archiving, and
public/private threads. Multiple navigators,
alternate view templates, and hotspot actions
for Web users.
Doc Library - Notes & doclbw7.ntf Notes and Web Document storage.
Web (7) (*) users
StdR6WebDocLib Features: Review workflow (serial and
parallel) and archiving.
Microsoft Office doclbm7.ntf Notes users Special version of the Document Library
Library (7) template dedicated to this application suite.
StdR6DocLibMS
Automatically loads and sizes the OLE object
to the window; and stores and supports
review cycles of documents created with suite
products.
Personal Journal (7) journal6.ntf Notes and Web Electronic diary where users can write and
users store private documents. Includes instructions
Std6Journal for customizing the database design.
TeamRoom (7) (*) teamrm7.ntf Notes and Web Team collaboration database. Maintains several
users document communication types to represent
StdR6TeamRoom meetings, discussions, and action items.
Features parallel review processing, archiving,
and newsletters.

479
480 Application Development with Domino Designer 7
Appendix B. Importing to and exporting from
views
Importing data allows you to move data from another system into a view. Exporting data allows you to
create a table of the data in a view for use in a presentation or report.

File formats you can export and import


No matter what type of data you want to import into a view, it’s best to import a small test file first. You
can quickly determine whether the import is working correctly and make any necessary corrections
before you import the entire file. The following table lists the types of files you can import and export.

File type File extensions File description


Comma Separated CSV For export only. The CSV format is an ASCII text file with
Value one record per line whose fields are separated by commas.
Lotus 1-2-3 and WKS, WK1, WRK, WR1, Entire worksheet or named range.
Symphony® WK3, WK4
To import a Microsoft Excel file, use Excel to save the file as
Microsoft Excel a 1-2-3 worksheet and then import it.

You cannot import a WRK or WR1 file to a view, but you


may export to either format. If you import a
multiple-worksheet file, only the worksheet that was most
recently viewed will be imported. If you import a specific
range from a multiple-worksheet file, only the information
from the most recently viewed worksheet will be imported.
Tabular text TAB, TXT, PRN, RPT ASCII text arranged in rows and columns; limit of 1536
characters per record, total.
Structured text LTR, CGN, STR ASCII text that retains its structure in fields and values;
shown as one record per page and one field per line; limit
of 256 bytes per simple text field.

Importing options
When you import a file into a view you have some choices for how to display the imported data.

Formatting options
You have three choices for generating the column titles and widths during an import.
v Choose ″View Defined″ if the column names and column widths in the source worksheet are identical
to the names and widths of the columns in the view.
v Choose ″WKS Title Defined″ if you’ve set up the worksheet so that the cells in the first row of the
worksheet match the column headers and fields in the view. The cells in the first row must be labels.
v Choose ″Format File Defined″ if you are using a column descriptor file (COL) that contains column
style instructions.

Including additional fields for imported documents


You can use the import option ″Calculate fields on form during document import″ if you want the newly
created document to contain all of the fields of the form you’re using for the import. Notes imports
information more quickly when you do not select this option. If you first import without selecting this

481
option and the results are not what you expect -- for example, fields that rely on other fields are empty or
incorrect -- import the worksheet again and choose this option.

Character translation file


Notes uses a character translation file (CLS) to translate foreign symbols and characters. The CLS file
must be in the Notes program directory.

Importing worksheets
Before you import a worksheet, you must create a form and a view to hold the imported data. When you
import a worksheet into the view, each worksheet row becomes an individual document, and each
worksheet column becomes a field. The original cell contents become the field contents. You can import
data into either main documents or response documents.

Notes doesn’t wrap lines of an imported worksheet. If a worksheet has more columns than a window can
display, use the horizontal scroll bars to see the full width of the worksheet. Notes can handle a
worksheet whose maximum text width is 22.75 inches; additional text is not displayed in the columns.

To import worksheet data into a view


The source file containing the worksheet must be on your local hard drive or on a file server to which
you are connected.
1. Select the database and open the view that will receive the source data.
2. Choose File - Import.
3. Select the name of the source file.
4. Select ″123 Worksheet.″
5. Click Import.
6. Select a form to use for the imported source data from the ″Use Form″ list.
7. Leave Main Document(s) selected in the ″Import as″ list, unless you are creating response
documents.
8. Select a ″Column format.″
If you select Format File Defined, enter the name of the COL file, including the complete operating
system path.
9. To import part of a worksheet, type a range name or range address in the WKS Range Name box.
You cannot import a 3-D range.

Note: If you import a multiple-sheet worksheet file, Domino imports only the sheet that was open
when the file was last closed, or, if importing a specified range, imports the range from that sheet.
10. (Optional) Select ″Calculate fields on form during document import.″
11. Click OK.

After importing, you can change the column font to a proportional space font, such as Courier, in the
view design pane to improve the display of worksheet data.

Importing tabular text


Tabular text is ASCII text arranged in rows and columns, separated by characters. When you import a
tabular text file into a view, each text row becomes an individual document, and each text column
becomes a field. The original cell contents become field contents.

There is a limit of 1536 total characters per record for tabular text imported into a view.

482 Application Development with Domino Designer 7


If the ASCII file and the view have different formats, create a column descriptor file (COL) to parse the
ASCII file so its individual components correspond to columns in the view or document fields. Then
when you import the ASCII file, select the ″Use format file″ option in the Tabular Text Import dialog box.

Viewing imported text


ASCII text files are monospaced. If columns in the view use a proportional font, text from the imported
file may be truncated. To avoid problems when importing text into a view, select Typewriter Fonts
(monospaced text) for the columns. You may want to resize columns to be sure the data is not truncated
on import. Truncation occurs only in the displayed text; no data is lost.

To import tabular text into a view


The source file containing the tabular text file must be on your local hard drive or on a file server to
which you are connected.
1. Select the database and open the view that will receive the source data.
2. Choose File - Import.
3. Select ″Tabular Text.″
4. Select the name of the source file.
5. Click Import.
6. Select a form to use for the imported source data from the Use Form list.
7. (Optional) Enter a ″Header Line Count″ or a ″Footer Line Count.″
To import only the data, specify the number of header and/or footer lines that you want Notes to
ignore in the source file.
8. Enter the number of ″Lines Per Page″ in the source file.
The ″Lines per Page″ setting establishes how many lines of data each Notes document receives. The
total number of lines in the imported documents are calculated as:
Lines Per Page - (Header Line Count + Footer Line Count)
9. Leave Main Document(s) selected in the ″Import as″ list, unless you are creating response
documents.
10. (Optional) Select ″Calculate fields on form during document import.″
11. (Optional) Select ″Use format file,″ click ″Choose format file,″ and select a column descriptor (COL)
file.
12. Click OK.

Importing structured text files


Structured text is ASCII text that retains its structure in fields and values. When you import a structured
text file into a view, the field names in the text file must correspond to the field names in a Notes
document in the view. To do this, create a form that contains the names of the fields you’re importing.

To import structured text into a view


The source file containing the structured text file must be on your local hard drive or on a file server to
which you are connected.
1. Select the database and open the view that will receive the source data.
2. Choose File - Import.
3. Select ″Structured Text.″
4. Select the name of the source file.
5. Click Import.
6. Select a form to use for the imported source data from the ″Use Form″ list.
7. Select an Inter-Document Delimiter to determine how to separate the records.

Chapter 25. Appendix B. Importing to and exporting from views 483


v Select ″Form-feed″ if the records in the source file are separated by a form feed (ASCII 12).
v Select ″Character Code″ if the records in the file are separated by a delimiter other than the
default, ASCII (form-feed).
8. Leave Main Document(s) selected in the ″Import as″ list unless you are creating response documents.
9. Do one of the following:
v Select Justify in the ″For body text″ list to wrap text to fit the Notes window.
v Select ″Preserve Line Breaks″ in the ″For body text″ list to maintain the existing line breaks in the
source file and add a return character at the end of each line of text.
10. (Optional) Select ″Calculate fields on form during document import.″
11. Click OK.

Creating a column descriptor (COL) file


A column descriptor (COL) file is an ASCII text file that contains instructions for mapping each column
in a source file into the fields and columns of a Notes view. Use a COL file only with tabular ASCII files
and worksheet files.
1. Use any ASCII text editor to create a file with the extension COL.
2. Use the column descriptor keywords and syntax to describe how to import each column from the
source file.
3. Write formulas in a section that is delimited by the keywords FORMULASTART and FORMULAEND.
4. Save and close the file.

Using a column descriptor file (COL ) to map a source file to a Notes


view
To import many files that have an identical structure into a view, create a column format descriptor
(COL) file. A COL file is like a map that defines which data from the source file goes into which Notes
field. Use a COL file only with tabular text files and worksheet files.

A COL file is an ASCII text file that contains a series of column definition statements, followed by a
section containing formulas that control the contents of fields in the Notes view. You write one statement
for each column in the source file. This statement describes how to format and map the columns in the
source file to columns in the Notes view. For best results, use exactly the same field names in the COL
file and in the Notes view.

Mapping a column to a field in a view


Enter the name of the column in the source file. The name should be identical to the name of the
corresponding field in a form. After you enter the column name, you can provide an optional statement
that specifies the data type of the data. You must, however, provide statements that define the format of
the source data -- that is, the delimiter or fixed position of the column.

If you use field names in the COL file that are not in the Notes view, Notes imports the data for those
fields, but the data won’t appear in the form or view until you create Notes field names that exactly
match those in the COL file. For example, if the COL file uses the field name ″Phone″ and the Notes view
uses ″PhoneNumber,″ data for the ″Phone″ field is present in the view but is not displayed. To correct
this problem, change the name of the existing Notes field to ″Phone,″ create a synonym for the existing
field, or create a new Notes field called ″Phone,″ and refer to the field in the view you’re using.

Specifying the data type of a column


When you import a file, Notes automatically determines the data type of each column, based on the
appearance of the data. For example, if the column in the source file contains data in the form 7/19/97,
Notes imports the data as dates.

484 Application Development with Domino Designer 7


As part of a field definition, you can provide an optional TYPE expression, followed by the appropriate
data type: Text, Number, or Datetime. For example, to import the contents of a field called DateOfBirth as
a date, enter the following field definition into the COL file:
DateOfBirth: TYPE DATETIME

The data in the source column must fit the data type you specify. If Notes encounters data that doesn’t
match the data type you specify, Notes imports the data as the type it most resembles.

Using formulas
The formulas that you write in a COL file describe how to modify the incoming values for display in the
view. These formulas, which follow the same rules as view selection formulas, may:
v Use @If formulas to test incoming values and display a specific value in the view, depending on the
result of the formula.
v Use text manipulation functions to modify the appearance of the incoming value -- for example, to
concatenate values or trim excess space characters from incoming values.
v Enter default values in fields.

Writing a COL file for a worksheet


To import worksheets using COL files, use these keywords:

WKSCOL
This keyword allows you to associate a field name with a specific worksheet column. The syntax for a
statement using this keyword is:

fieldname: WKSCOL columnletter

Where:
v fieldname is the name of the field in the view.
v columnletter is the letter of the source column in the worksheet that maps to that field name.

Only columns specified by the WKSCOL keyword will be imported.

RANGE
This keyword specifies the worksheet range to be imported. The syntax for a statement using this
keyword is:

RANGE rangename

Where:
v rangename is the name of the range in the worksheet.

The range must be a valid range name in the imported file.

If you use a RANGE statement, the first WKSCOL statement in the COL file must refer to the first
column in the range. For example, if the range starts at column D, the first WKSCOL statement in the
COL file must be:

Fieldname: WKSCOL D

Note that a RANGE statement in a COL file overrides any range name entered in the Worksheet Import
Settings box.

Chapter 25. Appendix B. Importing to and exporting from views 485


Writing a COL file for a tabular text file

Specifying the delimiter of a column


If the tabular text file uses a delimiter character to separate columns of data, you must use the UNTIL
keyword to specify the delimiter as part of each field definition.

For example, if the source data is delimited by commas, as in:

″Smith″, ″Robert″, ″Gryphon Real Estate″, ″555-1212″

and the view contains the following field names:

LastName, FirstName, Company, Phone

then the COL file will contain the following lines:


LastName: UNTIL ",";
FirstName: UNTIL ",";
Company: UNTIL ",";
Phone: UNTIL "";

If there is no delimiter at the end of the record (row), you identify the end of the last field as a null (″″).

Specifying the start, end, and width of a fixed-width column


If the tabular text file contains fixed-width columns of data, you use the START keyword along with
either the END or WIDTH keyword to define each field.

For example, if the source data contains a LastName field that is 12 characters wide and the view
contains a field named LastName, the COL file must contain the following column definition:
LastName: START 01 END 13

or
LastName: Start 01 WIDTH 12

The first column position is always 01, not 0.

The following lines of a COL file give two sets of instructions:


LastName: START 1 WIDTH 12
FirstName: TYPE TEXT START 13 END 20

The first line puts the contents of the first field, LastName, at position 1 and allows 12 characters for it.
The second line specifies that the data type of the FirstName field is text, begins the contents of the field
at position 13, and allows 8 characters for it.

Specifying the header, footer, and lines per page


The HEADER, FOOTER, and LINESPERPAGE keywords tell Notes to ignore headers and footers during
importing. The number of lines in the imported document are calculated as:

LinesPerPage - (HeaderLines + FooterLines)

For example, the following line of a COL file tells Notes to ignore 4 heading lines and 1 footer line and
sets the maximum number of lines per page to 66:
HEADERLINE 4 FOOTERLINE 1 LINESPERPAGE 66

486 Application Development with Domino Designer 7


The keywords may appear together or alone on a line in the file. These settings in a COL file override
values in the Tabular Text Import dialog box.

Writing formulas for COL files


All formulas in a COL file must appear after all the column definition statements. A COL file can have
only one FORMULASTART and FORMULAEND sequence. FORMULASTART must appear alone on a
line before the first formula. FORMULAEND must appear alone on a line after the last formula. Each line
of formulas between these keywords must end with a semicolon.

Example
The following COL file is used to import a 1-2-3 .WK3 file that records a checkbook balance.
;COL file for checkbook worksheet
;Discovers checkbook errors
Define five columns of input
date: WKSCOL A
chknum: WKSCOL B
amount: WKSCOL C
deposits: WKSCOL F
withdrawals: WKSCOL G
balance: WKSCOL K
;Define one column to mark bounced checks
FORMULASTART
FIELD bounced:=@IF(balance<0,"Yes"; "No");
FORMULAEND

In this example, columns D, E, H, I, and J in the worksheet are not imported into the view.

Exporting views
You can export a view to an ASCII file, a worksheet, a tabular text file, or a structured text file.

Exporting to an ASCII file with comma separated values


A comma separated value file (CSV) formats data as ASCII text with one record per line and with fields
separated by commas. When you export to a CSV file, you can choose between exporting all or selected
documents in a view. You can choose an export character set -- either Unicode, the International (UTF-8)
choice, or the default. You can also choose to include view titles in the exported file.

Notes on exporting as a CSV file


v When exporting to the CSV format, blank columns are replaced by a pair of quotes (″″ ″″) in the CSV
file.
v A category column is treated as the last column, so blank columns after the category columns are
ignored and not represented by quotes.
v Entries in collapsed sections of documents are not automatically exported. You must expand the
sections to export the data.

Exporting to a worksheet
When you export a view to a worksheet, each document becomes a row in the worksheet. Each field
becomes a column in the worksheet. The original field contents become cell contents. Column titles
become labels in the worksheet.

When you export a view to a new worksheet file, Notes exports the file in 1-2-3 WK1 format. Although
you can specify any extension with the file name, it’s best to keep the extension .wk1. When you open
the exported file in a newer release of 1-2-3, 1-2-3 automatically converts the file to its new format and
adds the appropriate extension.

Chapter 25. Appendix B. Importing to and exporting from views 487


If you change the exported file to WK2, WK3, or WK4 before opening it in a release of 1-2-3 that uses
that extension, and then open the file in 1-2-3 and attempt to add and save attributes, the new copy of
the file will be in conflict with the original, and you won’t be able to save your changes.

To export to a Microsoft Excel file, export the view as a 1-2-3 worksheet, and then save the file in 1-2-3 as
a Microsoft Excel file.

Exporting to a tabular text file


Tabular text is ASCII text arranged in rows and columns, separated by space characters. When you export
a view to a tabular text file, each document becomes a text row (line). Each field becomes a text
″column,″ separated by space characters. The original field contents become the ″cell″ contents. To see the
separation between columns in the exported view, use a monospaced font for the columns in the original
view.

The result of a tabular export may not look exactly like the view. Views use a proportionally spaced font,
but exports use a monospaced font. Export a few documents as a test. Then, if necessary, adjust the
column width settings in the view before you perform the whole export.

To display or edit the contents of a view in a Notes document, export the view to a tabular text file. Then
import the tabular text file into a Notes document.

Exporting to a structured text file


Structured text is ASCII text that retains its structure in fields and values. Exporting a view to structured
text creates a file containing the text of all the documents in the view, minus any rich text attributes.

To export a view
1. Select the database and open the view you want to export.
2. (Optional) Select specific documents to export only a subset of the view.
3. Choose File - Export.
4. Select the file format you’re exporting to.
5. Do one of the following:
v To replace an existing file, select a directory and file name from the list.
v To create a new file, enter a new file name.
v To append to an existing tabular text file, select a directory and file name from the list.
6. Click Export.
7. If you selected an existing file, do one of the following:
v To replace the file, click Replace.
v To append to an existing file, click Append.
8. Click ″All documents″ unless you selected specific documents in Step 2.
9. (Optional, for comma separated value format) Select an export character set.
10. (Optional, for 1-2-3 worksheet or tabular text formats) Select ″Include View titles″ to export the
view’s column headings to a worksheet or tabular text file.
11. (Optional, for structured text format) Change the inter-document delimiter and word-wrap settings if
you are exporting to a structured text file.
12. Click OK.

Delimiter and word wrap settings


v Delimiter - Choose Form Feed to use a form-feed to separate records in the file, or choose Character
Code to separate the records in the file with the ASCII code for a delimiter other than the default,
ASCII 12 (form-feed), such as:

488 Application Development with Domino Designer 7


32 Space
44 ,
45 -
58 :
59 ;
124 |
v Word wrap - Represents the number of characters at which each line wraps. The default is 75
characters.

Chapter 25. Appendix B. Importing to and exporting from views 489


490 Application Development with Domino Designer 7
Appendix C. Developing applications using MAPI
Lotus Domino Designer Release 6 and later supports the messaging application program interface
(MAPI), which allows mail integration between Domino and a MAPI-compliant messaging application,
such as Microsoft Outlook, Microsoft Office applications, or user-written C++ programs.

To support MAPI, Domino includes these service providers, which provide access to the Domino
message, directory, and transport services from simple or extended MAPI clients:
v Address Book provider
v Message Store provider
v Message Transport provider

Using the MAPI classes and methods supported by the Domino MAPI service providers, you can write
C++ programs to manipulate Domino objects.

A list of supported MAPI classes and methods appears at the end of this appendix.

The Address Book provider


The Address Book provider provides access to the Domino Directories.

The provider searches all name and address books on a server. To specify that the provider search
additional Domino Directories when doing address lookups, set the NAMES= setting in the NOTES.INI
file to include the file names of additional Domino Directories to search. Also, add the names of the
Domino Directories for Options - Addressing during MAPI profile setup.

The Address Book provider searches the Domino Directory for recipients’ names according to the order
specified in the profile.

Any simple or extended MAPI client can use the Address Book provider to access a Domino Directory.

The Message Store provider


If you are a Notes user receiving a message, you use the Message Store provider as the default MAPI
handler of messages (instead of using the Message Transport provider). In addition, messages are sent
using calls to the Message Store Message Interface rather than the MAPI spooler.

MAPI creates an Outbox folder the first time the Domino Message Store is accessed. The Outbox folder
captures outgoing messages you send from any extended or simple MAPI client (for example, Microsoft
Outlook or Office) when you are not connected to the LAN. Messages addressed to Notes recipients are
stored in the Outbox folder and placed in the local mail.box database in Domino. Once a connection to
the server is re-established, the messages are transferred. Messages addressed to non-Domino recipients
are placed in the outgoing mail queue, the exchange.box database, and the MAPI spooler handles them.

The MAPI folder interface is mapped onto Domino folders. You can create, move, copy, rename, and
delete folders. You can also create or delete file attachments in messages you compose while using the
client application. Attachment data is set or obtained using the IStream or IStorage interfaces. RTF and
native HTML are supported.

Note that some message store capabilities may not be supported.

491
The Message Transport provider
The Domino Mailer and Router transfers messages between Notes users. When the MAPI spooler
receives messages composed in a non-Notes message store, the Domino MAPI Message Transport
provider registers address and message types and sends messages to Notes recipients. If one or more
recipients are not of ADDRTYPE Notes, the Mail Router passes the messages to the MAPI spooler.

MAPI recipient types


Domino MAPI service providers handle delivery of messages to the following recipient types:
v Users who access their Domino mail files through a simple or extended MAPI client, such as Microsoft
Outlook
v Non-Notes users who access their non-Domino mail files through a simple or extended MAPI client,
such as Microsoft Outlook
v Notes users who access their Domino mail files from the Notes desktop
v Users of foreign mail systems that use a gateway as a backend

For information about MAPI service providers, see the topic ″Using Microsoft mail programs with Notes″
in Lotus Notes help.

Platforms and requirements for MAPI


The DLLs required for the Windows messaging subsystem are available only from Microsoft. Before you
install the Notes Client, you must install Microsoft Outlook 98 or Microsoft Outlook 2000.

Windows 98
When you install the Notes client, the Domino MAPI service providers are automatically installed. The
required DLLs for the Windows messaging subsystem are already present in Windows 95 and Windows
98.

Windows NT 3.51
The Domino MAPI service providers are available for Windows NT 3.51. Since Windows NT 3.51 does
not provide the Windows messaging subsystem, you must install the subsystem separately.

Windows NT 4.0
The Domino MAPI service providers are available for Windows NT 4.0. The required DLLs for the
Windows messaging subsystem are already present in Windows NT 4.0.

Windows 2000
The Domino MAPI service providers are available for Windows 2000. The required DLLs for the
Windows messaging subsystem are already present in Windows 2000.

Note: The Domino MAPI service providers can be installed and used for node installations on all of the
above Windows platforms.

Mail
The Domino MAPI service providers may only be used to access mail files that use the Lotus Domino
Designer 6 mail extended template (MAIL6EX.NTF). If you are upgrading from Release 5.x to Lotus
Domino Designer 6, you must upgrade your mail file to use the mail template provided in Lotus Domino
Designer 6. To use the service providers, both the client and the server must be running Lotus Domino
Designer 6.

492 Application Development with Domino Designer 7


The Profile Setup Wizard automatically installs all three service providers. When you create a Microsoft
Outlook Profile, the wizard uses information stored in the current Location document in Domino. You
make modifications to the Office (Network) Location document to configure the location for server-based
mail.

To use workstation-based mail, you modify the Local Mail (Disconnected) Location document. Note that
the Location type in the local mail document must be either Local Area Network or No Connection. The
Mail section of the location document must specify information about the mail file location, the name of
the mail file, and the domain.

Note: During logon to the service providers, the settings for MDB_NO_DIALOG and AB_NO_DIALOG
flags are ignored. As a result, the user is always prompted for a password.

Address Book template


To access Domino Directories through the Address Book Provider, you must apply the Domino Directory
template (PUBNAMES.NTF) to the design. If you are using workstation-based mail, apply the Personal
Address Book template (PERNAMES.NTF) to the design of the Personal Address Books.

MAPI classes and methods


Not all supported methods are supported for all objects.

MAPI classes Supported methods


CLASS IMAPIContainer GetContentsTable GetHierarchyTable OpenEntry SetSearchCriteria
CLASS IABLogon Advise CompareEntryIDs GetLastError Logoff OpenEntry Unadvise
GetOneOffTable
CLASS IABProvider Logon Shutdown
CLASS IMAPIControl Activate GetLastError GetState
CLASS IMAPIFolder CopyFolder CopyMessages CreateFolder CreateMessage DeleteFolder
DeleteMessages EmptyFolder GetMessageStatus SaveContentsSort
SetMessageStatus SetReadFlags
CLASS IMAPIProp CopyProps CopyTo GetIDsFromNames GetLastError GetNamesFromIDs
GetPropList GetProps OpenProperty SaveChanges SetProps DeleteProps
CLASS IMAPITable Abort Advise CreateBookmark FindRow FreeBookmark GetLastError
GetRowCount GetStatus QueryColumns QueryPosition QueryRows
QuerySortOrder Restrict SeekRow SeekRowApprox SetColumns Unadvise
SortTable
CLASS IMessage CreateAttach DeleteAttach GetAttachmentTable GetRecipientTable
ModifyRecipients OpenAttach SetReadFlag SubmitMessage
CLASS IMsgStore AbortSubmit Advise CompareEntryIDs FinishedMsg GetOutgoingQueue
GetReceiveFolder NotifyNewMail OpenEntry SetLockState SetReceiveFolder
StoreLogoff Unadvise
CLASS IMSLogon Advise CompareEntryIDs GetLastError Logoff OpenEntry Unadvise
CLASS IMSProvider CompareStoreIDs Logon Shutdown SpoolerLogon
CLASS IXPLogon AddressTypes EndMessage FlushQueues Idle (supported, but not used for
tightly-coupled message store) OpenStatusEntry Poll (supported, but not used for
tightly-coupled message store) RegisterOptions StartMessage (supported, but not
used for tightly-coupled message store) SubmitMessage TransportNotify
CLASS IXPProvider Shutdown TransportLogon
CLASS IMailUser All methods supported for this class
CLASS IAttach All methods supported for this class

Chapter 26. Appendix C. Developing applications using MAPI 493


MAPI classes Supported methods
CLASS IMAPIAdviseSink All methods supported for this class
CLASS IMAPIProfile All methods supported for this class
CLASS IMAPIContainer All methods supported for this class
CLASS IMAPIStatus All methods supported for this class
CLASS IPropData All methods supported for this class
CLASS ITableData All methods supported for this class

494 Application Development with Domino Designer 7


Appendix D. Features to avoid using in Web
applications
Developers creating applications specifically for the Web, or for the dual purpose of serving Notes and
Web clients, should review the following tables for features that are not supported on the Web.
v @functions
v Actions and agent properties
v Calendar features
v Field properties
v Form properties
v Formatting features
v Frame properties
v Horizontal rule properties
v Hotspot properties
v Navigator properties
v Table properties
v Text styles
v View properties
v Features that are not supported by the Domino view applet

Domino @functions that are not supported on the Web


The following groups of @functions are not supported in Web applications or are supported differently
than they are in Domino applications.

@Function Comments
@Certificate
@DbCommand Available only with the syntax
@DbCommand(″Domino″;″ViewNextPage″) and @DbCommand
(″Domino″;″ViewPreviousPage″) to create a link to the next/previous
page in a view. Not available in other contexts.
@DDEExecute @DDEInitiate @DDEPoke
@DDETerminate
@DocMark @DeleteDocument
@DocChildren @DocDescendants @DocLevel Not available except in column formulas.
@DocNumber @DocParentNumber
@DocSiblings
@IsCategory @IsExpandable @Responses
@DialogBox @PickList @Prompt
@IsModalHelp
@GetPortsList
@Environment @SetEnvironment Use predefined field names to gather information about the Web
ENVIRONMENT keyword user’s environment by requesting Common Gateway Interface (CGI)
environment variables.
@MailSend

495
@Function Comments
@Domain @MailDbName
@MailEncryptSavedPreference
@MailEncryptSendPreference
@MailSavePreference @MailSignPreference
@IsAgentEnabled
@IsDocBeingMailed
@Unique @URLGetHeader @URLHistory
@UserPrivileges
@Platform for user’s platform. Returns server’s platform only. Use @ClientType to distinguish
between Web and Domino users.

Domino actions and agent properties that are not supported on the
Web
Avoid using the following actions and agent features in a Web application.

Agents Comments
Manually From Actions Menu Web users do not have an Actions menu. Run agents with actions
or buttons that use @Command([RunAgent]),
@Command([ToolsRunMacro]), or through the WebQuerySave and
WebQueryOpen form events.
″If Documents Have Been Pasted″ and the The concepts of ″pasted documents″ and ″selected documents″
document selection option ″Selected don’t apply to Web applications.
documents″
Form and view actions
Include action in Action menu Web users do not have an Actions menu. Use the option ″Include
action in button bar″ instead.
Default form and view actions that use system Use supported @commands to create the equivalent actions.
commands (such as *Edit Document,
*Categorize)
Programs for actions and agents
Simple actions
LotusScript for forms, actions, and buttons Supported for agents only.
″Alias a folder″ simple action Dragging and dropping to folders is not available on the Web.

Domino calendar features that are not supported on the Web


Avoid using these calendar features in a Web application.
v Embedded Group Scheduler
v Date Picker
v Time control
v Duration control

496 Application Development with Domino Designer 7


Domino field properties that are not supported on the Web
Avoid using the following field features in a Web application.

Notes/FX fields Comments


Field Info properties
Compute After Validation
Give this field default focus
Control properties
Options Display entry helper button is not supported.
Advanced properties
Help description
Enable encryption for this field Web users cannot read data in encrypted fields.
Sign if mailed or saved in section
Names fields/Control properties
Choices (for Names fields) ″Use Address dialog for choices,″ ″Use Access Control List for
choices,″ and ″Use View dialog for choices″ are not supported.
Web user access to databases is based on the authenticated name.
Check box fields
Check box selection order For some browsers, the order of the data returned from multiple
selections in a checkbox may be different from the selection
order. The data itself remains the same, but the order returned is
different.

Domino form properties that are not supported on the Web


Avoid using the following form features in a Web application.

Form Info properties Comments


Versioning
Anonymous forms
Merge replication conflicts
Store form in document - Edit mode Read mode is supported, but do not use for documents that need
to be created or edited on the Web.
Disable field exchange
Automatically refresh fields
Defaults properties
On Create: Inherit entire selected document into ″Inherit entire selected document into rich text field ″as rich text″
rich text field -- ″as Link″ and ″as Collapsible is supported. The documents must reside in the same database
rich text″ and the database property, ″Web Access: Use JavaScript when
generating pages″ must be selected.
On Open: Show context pane
Security properties
Default encryption keys Not applicable to Web.
Disable printing/ forwarding/copying to
clipboard
Form elements

Chapter 27. Appendix D. Features to avoid using in Web applications 497


Form Info properties Comments
Layout regions Use tables to align form components instead.
Pop-up hotspots
ActiveX components, OLE, and OCX objects Not supported on Macintosh, UNIX, and OS/2 platforms.
Supported for display on Windows NT and Windows 95
platforms, but users can’t save changes made to objects.
Border controls for tables If the top left cell of a table has a border, the entire table is
displayed with a border; otherwise, there is no border because of
limitations with HTML.

Domino formatting features that are not supported on the Web


Avoid using the following formatting features in Web applications.

Feature Comments
Bullet characteristics in an ordered list (sizing The color and size of a bullet in an ordered list cannot be
and color) manipulated on the Web.
International characters The international characters that are supported on the Web vary
depending on the browser version and the fonts installed on the
platform used to view and edit text on the Web.
First-line indent or outdent in a paragraph
Full justification paragraph alignment
Images Avoid this feature if editing a document with both the Notes
client and the editor applet.
Ordered lists Avoid this feature if the list will be edited in the Notes client and
the editor applet. Ordered lists are supported if they are edited
with the editor applet only.
Pasting text There are limitations for pasting text in the editor applet. See
Designing Fields for information about using the editor applet for
editing rich text fields on the Web.
Tabs
Tables Avoid this feature if editing a document with both the Notes
client and the editor applet.
Unordered lists Avoid this feature if the list will be edited in the Notes client.
Unordered lists are supported if they are edited with the editor
applet only.

Domino frame properties that are not supported on the Web


Avoid using this frame feature in a Web application.

Basics properties Comments


Default target for links in frame Targets may be set in both the Frame Properties box and the
design element contained by that frame. The design element in
this case may be a form, page, or view. If a target is set in the
Frame Properties box of a Web application, but not in the
design element, and the design element is later replaced, the
links in the frame will not go to the target specified in the
Frame properties. To avoid this, specify the same target frame in
both the Frame properties and the design element.

498 Application Development with Domino Designer 7


Domino horizontal rule properties that are not supported on the Web
Avoid using color rules in a Web application. Gradient color is not supported on the Web.

Domino hotspot properties that are not supported on the Web


Avoid using hotspot borders in a Web application.

Domino navigator properties that are not supported on the Web


Avoid using the following navigator features in a Web application.

Navigators Comments
Info properties
Auto adjust panes at runtime
Objects
Polyline objects Polyline objects display on the Web, but clicking them has no
effect.
HiLite properties
Highlight when... options for navigator objects

Domino table properties that are not supported on the Web


Avoid using the following table features in a Web application.

Table Layout properties Comments


Column spacing This property is not supported in Web applications, but may
affect the Width property of a cell, which is supported on the
Web.
Minimum height
Row spacing
Table Width ″Same as window″ setting is ignored in a Web application.
Cell Borders properties
Color Color settings for cell borders are not supported on the Web
Cell Border Style The style options, Ridge and Groove, are not supported on the
Web.
Cell Border Thickness Border thickness settings greater than 1 are not supported.
Table/Cell Background properties
Style Solid is the only color option supported on the Web. Gradients
will appear as the first color.
Table Borders properties
Border style Determined by individual cell borders.
Border color The table color is used.
Border effects Width is not supported.
Thickness
Table Margins properties
Left

Chapter 27. Appendix D. Features to avoid using in Web applications 499


Table Layout properties Comments
Right
Table wrap
Compatibility
Table Rows properties
Show only one row at a time ″Switch rows every n milliseconds″ and ″transitions″ are not
supported.

Domino text styles that are not supported on the Web


Avoid using the following text features in a Web application.

Font properties Comments


Default fonts (Helvetica and Times Roman in
Windows)
Alignment and Tab properties
Full Justification and No Wrap alignment styles
Interline spacing A line spacing which is not a whole number will be rounded up
to the nearest whole number. For example, a line spacing of 1.5
will be rounded up to 2.
Formatting aids, such as tabs, indents, outdents, HTML doesn’t support these formatting styles. Use tables to
and extra spaces align form components. Use the text style Pass-Thru HTML to
use HTML formatting styles.
Text effects properties
Shadow, Emboss, and Extrude text styles

Domino view and folder properties that are not supported on the Web
Avoid using the following view and folder features in a Web application.

Views and folders Comments


Folders Private folders are not supported in outlines on the Web.
Views Private views are not supported.
Options properties
Show in View menu Web applications do not have a View menu. To exclude a
view from the folders navigator, use the Design - Design
Properties box to hide the view from Web users, or include
the view name in parentheses -- for example, (HiddenView).
On Open: Go To... options
On Refresh options
Style properties
Unread rows Show selection margin is supported for views rendered as
HTML, but not for view applets.
Alternate rows

Beveled headings
Advanced properties

500 Application Development with Domino Designer 7


Views and folders Comments
Refresh index options Views can be reindexed by a Domino server.

Discard index options


Column Info properties
Show twistie when row is expandable Expand/collapes icons (twisties) are always shown.

Note: If you embed a view, you cannot dynamically sort a categorized column on the Web or in a Notes
client.

Features that are not supported by the Domino view applet


Avoid using the following Domino view applet features in a Web application.

Feature Comments
Pass-Thru HTML
View Info properties
Calendar views Calendar views are not supported. The HTML Calendar view
will be generated even if view applet is selected.
Options properties
On Refresh None of the ″on refresh″ options are supported.
Style properties
Unread rows color
Beveled headings
Lines per heading
Shrink rows to content
Row spacing
Advanced properties
Refresh index
Discard index
Unread marks
For ODBC Access
Active Link
Unvisited Link
Visited Link
Restrict initial index build to designer or
manager
Font properties The available fonts are limited to a subset of fonts supported by
Java.
Title properties
Font The available fonts are limited to a subset of fonts supported by
Java.
Advanced properties
Show values in this column as links

Chapter 27. Appendix D. Features to avoid using in Web applications 501


502 Application Development with Domino Designer 7
Appendix E. URL commands for Web applications
You have a variety of options for programming a Web site. You can directly manipulate objects such as
documents or views in an application using Domino URL commands. Adding Domino URL commands
as HTML in forms gives users shortcuts for navigating databases and performing other tasks quickly.

You can also use the Lotus formula language of @functions and @commands to allow users to work in a
Web application. For information about using @commands and @functions, see the Domino Designer
Programming Guide.

You can also use Java, JavaScript, Visual Basic Script, Perl script, and CGI programs to automate tasks in
a Web application.

For more information on programming a Web application, see ″Programming Domino for Web
Applications″ in the Domino Designer Programming Guide.

Domino URL Commands


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

The Domino URL command syntax


Domino URL commands have the syntax:

http://Host/DominoObject?Action&Arguments

Where
v Host = a DNS entry or an IP address
v DominoObject = a Domino construct (for example, a database, view, document, form, navigator, agent,
and so on). URL commands for accessing DominoObjects use the following syntax:
http://Host/Database/DominoObject?Action&Arguments where Database = the database in which the
DominoObject resides.
v Action = the desired operation on the specified DominoObject (For example, ?OpenDatabase,
?OpenView, ?OpenDocument, ?EditDocument, ?OpenForm, and so on).
v 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
v Domino URLs do not use the server name. Host identifies the server.
v You can specify the maximum size and other limits of a URL command in the Server record, in fields
listed under the Internet Protocols -HTTP tab.
v Special identifiers used in Domino URL commands include: $defaultView, $defaultForm, $searchForm,
$file, $icon, $help, $about, and $first.
v DominoObject can be any of the following: for a database, the database name or replica ID; for other
objects, the DominoObject’s name, universal ID, 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, or $defaultView.
v A Notes database can be specified by its file name, for example leads.nsf, or by placing a double
underscore before the replica ID and adding an .nsf suffix to the end. For example, specify
__852562F3007ABFD6.nsf

503
v A DominoObject’s name and universal ID are identical in all replicas of a database. 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.
v Action can be explicit or implicit. Examples of explicit actions include ?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.
v To require user authentication, append the Login argument to any Domino URL.
v Because URLs cannot contain spaces, use the + (plus sign) or the hex value %20 to represent a space.
For example:
http://www.mercury.com/discussion.nsf/By+Author
Http://www.mercury.com/discussion.nsf/By%20Author
v If a name contains a mixture of spaces and the ″+″ character, it may be necessary to use %20 to
indicate the space. For example, if the document’s key is ″Smith + Jones″ then
http://www.mercury.com/leads.nsf/ByCompany/Smith%20%2B%20Jones?OpenDocument
and
http://www.mercury.com/leads.nsf/ByCompany/Smith%20+%20Jones?OpenDocument
will work but
http://www.mercury.com/leads.nsf/ByCompany/Smith+++Jones?OpenDocument
will not.
v Where a name or argument contains a symbol that is not part of the URL syntax or would conflict with
URL syntax, such as plus signs (+), slashes (\ or /), or ampersands (&), use the escaped form %xx
(where xx is the hex ascii value) to represent the symbol. For example, the following URL opens the
document which has the key value ″Smith&Jones, Inc.″:
Http://www.mercury.com/leads.nsf/By%20Company/Smith%26Jones,%20Inc.?OpenDocument
v Slashes and backslashes in URL path components are not distinguishable, even if escaped. (This is
because the first step in URL processing is to unescape all escaped characters and to change ’\’ to ’/’.)
The result is that some names will be ambiguous or not addressable. For example while two views,
one named ″a/b\c/d″ and the other ″a\b/c\d″ are different in the designer, they cannot be named
uniquely with a URL.
v Document keys containing slashes and/or backslashes are addressable with the following restrictions:
– You must supply the ?OpenDocument command argument in the URL. For example if the document
key is ″Smith/Jones″ the following URL will find the document:
http://www.mercury.com/leads.nsf/ByCompany/Smith/Jones?OpenDocument
but this one will result in ″Error 404 - Entry not found in index″:
http://www.mercury.com/leads.nsf/ByCompany/Smith/Jones
– The document title as stored in the database must use all ″/″ or ″\″. If it uses a mixture, it won’t be
found.
– Using slashes (both kinds) in view names along with slashes in document titles may result in
ambiguities and ″unreachable″ documents. If you have a view named ″a″ which has a document in
it titled ″b/c″, and a view named ″a\b″ which contains a document ″c″, the URL
/database.nsf/a/b/c?OpenDocument will open the document in the view a/b.
– Document titles which begin or end with the ″/″ or ″\″ character won’t be found.
v The percent character (″%″) is not allowed in a URL, even in ″escaped″ form. This is to help prevent
attacks which attempt to mask their intent by escaping the escape character.
v Separate arguments with an ampersand (&). For example:
http://www.mercury.com/leads.nsf/By+Salesperson?OpenView&ExpandView
v Separate hierarchical names with a 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

504 Application Development with Domino Designer 7


v If you are generating your own URLs for any part of an application, use simple aliases whenever
possible to avoid URLs with unsupported characters.
v URL commands may also refer to databases with .nsf4, .nsf5, .nsf6 or .box suffixes. They may also refer
to template files (.ntf), but these databases can only be opened in preview mode.
v Selecting ″Web access: Use JavaScript when generating pages″ in Database properties will enable you to
compute URLs attached to buttons and hotspots on the Click event. If this option is not selected, URLs
attached to buttons and hotspots will be computed when the page is generated. Enabling this property
can be useful if you’re using editable fields on a form.

URL commands for opening servers, databases, and views


The following commands access servers, databases, views, ″About This Database″ documents, Help
documents, and database icons. Databases must be in the notes\data directory or a subdirectory of the
notes\data directory in order to be accessed by a URL command, except server commands such as?Login,
?Logout, and ?Redirect. You may use the name of a database that does not exist in the server command
syntax if a database is required, as it is with Microsoft Internet Information Server. If the database
referenced in a server command does not exist, it will be ignored. Use ?Redirect to redirect doclinks
across servers. Hidden design elements are hidden from the server too; you can’t use Domino URL
commands to access documents in hidden views.

CAUTION:
If the database property ″Do Not Allow URL Open″ is set, these URL commands are disabled.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

Redirect

Syntax
http://Server/Dummy.nsf?Redirect&Name=notesserver&Id=To=encodedurl

Where:
v http://Server refers to the Web server which is generating the URL.
v Name=notesserver specifies a Domino server name in its common or abbreviated form. This is optional
when the ″By Database″ setting on the server is enabled.
v ID=repid indicates the replica ID of the database to be located. This is an optional argument.
v To=encodedurl specifies the rest of the URL.

Example
Http://mercury.com/dummy.nsf?Redirect&Name=Mister%2FHankey&Id=0525666D0060ABBF&To=
%FAView%3FOpenView

Note: If you force a logout using the ?Logout command, you can redirect to another Web site using the
&RedirectTo parameter.

OpenDatabase
Syntax
http://Host/__DatabaseReplicaID.nsf?OpenDatabase

Chapter 28. Appendix E. URL commands for Web applications 505


Examples
http://www.mercury.com/leads.nsf?OpenDatabase

http://www.mercury.com/sales/discussion.nsf?OpenDatabase

http://www.mercury.com/__852562F3007ABFD6.nsf?OpenDatabase

OpenView

Syntax
http://Host/Database/ViewName?OpenView

http://Host/Database/ViewUniversalID?OpenView

http://Host/Database/$defaultview?OpenView

Examples
http://www.mercury.com/leads.nsf/By+Salesperson?OpenView

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F300702264?OpenView

http://www.mercury.com/leads.nsf/$defaultview?OpenView

Optional arguments for OpenView


Append optional arguments to refine the URL. Combine any of the following arguments for the desired
result except where otherwise noted.

Collapse=n

Where n is the row number to display in collapsed format in a hierarchical view. Do not combine this
argument with the ExpandView or CollapseView arguments.

CollapseView

Displays the view in collapsed format

Count=n

Where n is the number of rows to display

Expand=n

Where n is the row number to display in expanded format in a hierarchical view. Do not combine this
argument with the ExpandView or CollapseView arguments.

ExpandView

Displays the view in expanded format

RestrictToCategory=category

Sets the category for ″Show Single Category″ object

Where category is the category to be displayed in the view.

506 Application Development with Domino Designer 7


Start=n

Where n is the row number to start with when displaying the view. The row number in a hierarchical
view can include sub indexes (for example, Start=3.5.1 means the view will start at the third main topic,
sub-topic 5, document 1).

StartKey=string

Where string is a key to a document in the view. The view displays at that document.

Examples
http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&
CollapseView

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&
ExpandView

http://www.mercury.com/leads.nsf/By+Category?OpenView&RestrictToCategory=pricing

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&
Start=3&Count=15

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?OpenView&
StartKey=F

ReadViewEntries
Use this command to access view data in XML form without appearance attributes such as fonts, list
separators, date formats, HTML settings, view templates and frame redirections.

Note: This command only returns the documents a user is allowed to access.

Syntax
http://Host/Database/ViewName?ReadViewEntries

http://Host/Database/ViewUniversalID?ReadViewEntries

http://Host/Database/$defaultview?ReadViewEntries

Examples
http://www.mercury.com/leads.nsf/By+Salesperson?ReadViewEntries

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F300702264?ReadViewEntries

http://www.mercury.com/leads.nsf/$defaultview?ReadViewEntries

Optional arguments for ReadViewEntries


Append optional arguments to refine the URL. Combine any of the following arguments for the desired
result except where otherwise noted.

Collapse = n

Where:

Chapter 28. Appendix E. URL commands for Web applications 507


n is the row number to display in collapsed format in a hierarchical view. Do not combine this argument
with the ExpandView or CollapseView arguments.

CollapseView

Displays the view in collapsed format

Count = n

Where:

n is the number of rows to display

Expand = n

Where:

n is the row number to display in expanded format in a hierarchical view. Do not combine this argument
with the ExpandView or CollapseView arguments.

ExpandView

Displays the view in expanded format

KeyType = text|time (

Specifies the type of StartKey. The default when no argument is specified is text. Setting the KeyType to
time allows you to use a time value as the value for StartKey which dictates from what row to display
the view and the value for UntilKey, which specifies where to stop display of the view. If
&KeyType=time is specified, then &StartKey and &UntilKey may be ISO date time values. For example,
you might use the time value 20020101T140000,00Z to represent 9:00AM Eastern standard Time in
Coordinated Universal Time (UTC) or Greenwich Mean Time (GMT), or you might use the time value
20020101T090000,00-05 to represent the same date and time in local time plus offset.

PreFormat

Causes all data types to be converted to text on the server. Text lists, numbers, dates and lists of numbers
are converted to text before being sent. The server’s locale is used for all formatting. Without this
argument, the XML output stream contains information in structured, locale-neutral formats.

ResortAscending = column number

ResortDecending = column number

Where:

column number is the 0-based number of the column in the view you wish to resort in ascending or
descending alphanumeric order.

RestrictToCategory = category

Sets the category for the ″Show Single Category″ object

Where:

category is the category to be displayed in the view

508 Application Development with Domino Designer 7


Start = n

Where:

n is the row number to start with when displaying the view. The row number in a hierarchical view can
include subindexes (for example, Start=3.5.1 means the view will start at the third main topic, subtopic 5,
document 1).

StartKey = string

Where:

string is a key to a document in sorted view. The view displays at that document. In cases where there is
no match for the StartKey, the next document is returned. So, for example, if the StartKey is ″A″ and
there are no documents that begin with ″A″, StartKey returns the first document that begins with ″B.″

UntilKey = string

UntilKey is only valid when used with StartKey. It allows you to display the range of view entries
beginning with the document specified by StartKey until the document specified by UntilKey. For
example, &StartKey=A&UntilKey=B would give you all the entries that start with A. Use the &Count
keyword to further limit the number of entries returned within any given range.

Examples
http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?
ReadViewEntries&CollapseView

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?
ReadViewEntries&ExpandView

http://www.mercury.com/leads.nsf/By+Category?ReadViewEntries&PreFormat

http://www.mercury.com/leads.nsf/By+Category?ReadViewEntries&RestrictToCategory=pricing

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?
ReadViewEntries&Start=3&Count=15

http://www.mercury.com/leads.nsf/DDC087A8ACE170F8852562F30070226400000196?
ReadViewEntries&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.

Chapter 28. Appendix E. URL commands for Web applications 509


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

URL commands for opening framesets

OpenFrameset
Note: The URLs shown below are for example only. They do not point to existing Web sites.

Syntax
http://Host/Database/FramesetName?OpenFrameset

http://Host/Database/FramesetUNID?OpenFrameset

Examples
http://www.mercury.com/discussion.nsf/main?OpenFrameset

http://www.mercury.com/discussion.nsf/35AE8FBFA573336A852563D100741784?OpenFrameset

URL commands for opening agents, forms, and navigators


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

Note: The URLs shown below are for example only. They do not point to existing Web sites.

OpenAgent

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

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

Note: Agents may only be referred to by name. The use of UNID is not supported when referring to an
agent.

510 Application Development with Domino Designer 7


OpenForm

Syntax
http://Host/Database/FormName?OpenForm

http://Host/Database/FormUniversalID?OpenForm

http://Host/Database/$defaultform?OpenForm

Examples
http://www.mercury.com/products.nsf/Product?OpenForm

http://www.mercury.com/products.nsf/625E6111C597A11B852563DD00724CC2?OpenForm

http://www.mercury.com/products.nsf/$defaultform?OpenForm

Optional argument forOpenForm


ParentUNID = UniqueIDNumber

Where UniqueIDNumber is the document ID of the parent document, which is used in response forms or
when the form property ″Formulas inherit values from selected document″ is selected.

Syntax
http://Host/Database/FormUniversalID?OpenForm&ParentUNID

Example
http://www.mercury.com/products.nsf/40aa91d55cle4c8285256363004dc9e0?OpenForm&
ParentUNID=6bc72a92613fd6bf852563de001f1a25

OpenNavigator

Syntax
http://Host/Database/NavigatorName?OpenNavigator

http://Host/Database/NavigatorUniversalID?OpenNavigator

Examples
http://www.mercury.com/products.nsf/Main+Navigator?OpenNavigator

http://www.mercury.com/products.nsf/7B5BC17C7DC9EB7E85256207004F8862?OpenNavigator

ReadForm
Use the ReadForm command to display a form without showing its editable fields. ReadForm is useful
for displaying a form as a simple Web page.

Syntax
http://Host/Database/FormName?ReadForm

http://Host/Database/FormUniversalID?ReadForm

http://Host/Database/$defaultform?ReadForm

Chapter 28. Appendix E. URL commands for Web applications 511


Examples
http://www.mercury.com/home.nsf/Welcome?ReadForm

http://www.mercury.com/products.nsf/625E6111C597A11B852563DD00724CC2?ReadForm

http://www.mercury.com/products.nsf/$defaultform?ReadForm

URL commands for opening resources


The following URL commands open resources, design elements that allow you to import, store, and
deploy a variety of file types in an NSF application. Resources are widely used with Web applications
and applications designed for use with WebDAV.

For more information on resources, see ″Sharing non-NSF files″.

OpenImageResource
Allows you to open a graphic resource in an application.

Syntax
http://Host/Database/ImageResourceName?OpenImageResource

Where:
v ImageResourceName is the name of the image file being accessed.

Examples
http://www.mercury.com/leads.nsf/TopHeader.gif?OpenImageResource

OpenFileResource
Allows you to open a file resource in an application.

Syntax
http://Host/Database/FileResourceName?OpenFileResource

Where:
v FileResourceName is the name of the file being accessed.

Examples
http://www.mercury.com/leads.nsf/JSLibrary.js?OpenFileResource

URL commands for creating, deleting, editing, opening, and saving


documents
The following commands manipulate documents in a database. Hidden design elements are hidden from
the server too; you can’t use Domino URL commands to access documents in hidden views.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

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.

512 Application Development with Domino Designer 7


Syntax
http://Host/Database/Form?CreateDocument

http://Host/Database/FormName?CreateDocument

Where:

FormName is the name of the form being accessed.

Examples
http://www.mercury.com/products.nsf/b9815a87b36a85d9852563df004a9533?CreateDocument

http://www.mercury.com/products.nsf/basketballs?CreateDocument

DeleteDocument

Syntax
http://Host/Database/View/Document?DeleteDocument

Example
http://www.mercury.com/products.nsf/By+Part+Number/PC156?DeleteDocument

EditDocument
Syntax
http://Host/Database/View/Document?EditDocument

Example
http://www.mercury.com/products.nsf/By+Part+Number/PC156?EditDocument

Note: Rich text fields containing hidden text will be visible to Web users with Editor access to
documents.

Note: The following items may be lost or corrupted if they are in a rich text field which is edited with a
Web browser using Domino Web Server:
v embedded images -- may be visible when editing, but will be lost when the document is saved;
v tab tables -- only the visible row will be saved;
v ″hide when″ paragraphs which are hidden from the Web -- the entire paragraph will be lost when the
document is saved.

Avoid using these items in a rich text field if that field is to be edited with a Web browser.

OpenDocument

Syntax
http://Host/Database/View/Document?OpenDocument

Where:

Document is any of the following:

Chapter 28. Appendix E. URL commands for Web applications 513


v DocumentKey -- the contents of the first sorted column in the specified view.
v DocumentUniversalID

$first

The first document in the view.

Examples
http://www.mercury.com/products.nsf/By+Part+Number/PC156?OpenDocument

http://www.mercury.com/leads.nsf/By+Rep/35AE8FBFA573336A852563D100741784?OpenDocument

SaveDocument
The SaveDocument command is used as the POST action of a document being edited. Domino updates
the document with the new data entered in the form.

Syntax
http://Host/Database/View/Document?SaveDocument

Example
http://www.mercury.com/products.nsf/a0cefa69d38ad9ed8525631b006582d0/
4c95c7c6700160e2852563df0078cfeb?SaveDocument

URL commands for opening documents by key


The following commands allow you to open a document by using the key value of the first sorted
column of a view, such as a document name, or to generate a URL to link to a document by key. Hidden
design elements are hidden from the server too; you can’t use Domino URL commands to access
documents in hidden views, unless you’ve hidden the view by surrounding its name in parentheses,
rather than using the Hide tab in the Properties box.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

Using Domino URLs to access a document


To open a document by key, create a sorted view with the sort on the first key column. Then use a URL
to open the document.

Syntax
http://Host/Database/View/DocumentName?OpenDocument

Where:
v View is the name of the view. To access a document regardless of the view, specify the document by its
universal ID and substitute a zero (0) for the view name.
v 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.

514 Application Development with Domino Designer 7


Note that View can be a UNID, or view name. In addition, the implicit form of any of these commands
will work when appropriate. For example, you can omit the OpenDocument argument in a URL
command and the document will still open because the command is automatically interpreted as
OpenDocument. (EditDocument and DeleteDocument must be explicit commands.)

Examples
http://www.mercury.com/register.nsf/Registered+Users/Jay+Street?OpenDocument

http://www.mercury.com/register.nsf/0/466c5172561e1c5c852566c2005f6bbb?OpenDocument

Using @commands to link to a document


For information about using @commands in Web applications, see Features to Avoid Using in Web
Applications.

Using Domino URLs to access attachments


When Domino saves a file attachment with a document, it generates a URL so it can retrieve the file later.
An attachment generates a URL whose last component is the original file name. For example:
http://domino.lotus.com/domdown.nsf/ViewUNID/DocumentUNID/$File/DOMINO.EXE

ViewUNID can indicate a ViewID or a ViewName. DocumentUNID can be a DocumentKey. This allows
you to create URL links to attachments by supplying a view name and document key.

By default, the browser uses the name specified in the URL to save the file.

URL commands for opening pages


The following command will open a Web page using its name or UNID.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

OpenPage

Syntax
http://Host/Database/PageName?OpenPage

http://Host/Database/PageUNID?OpenPage

Examples
http://www.mercury.com/discussion.nsf/products?OpenPage

http://www.mercury.com/discussion.nsf/35AE8FBFA573336A852563D100741784?OpenPage

Optional arguments for OpenPage and OpenDocument


The following arguments manipulate outline controls on pages and documents. The arguments for
OpenPage and OpenDocument commands use the same syntax regardless of the command.

CollapseOutline=[n]

Where n is the triangle at the top level of the outline. It is possible to collapse triangles in hierarchical
order. For example, &CollapseOutline=2.1.3 will collapse the second triangle at the top level of the
outline, the first triangle at the second level, and the third triangle at the third level.

Chapter 28. Appendix E. URL commands for Web applications 515


Syntax
http://Host/Database/PageName?OpenPage&CollapseOutline=n

http://Host/Database/PageUNID?OpenPage&CollapseOutline=n

Examples
http://www.mercury.com/sales.nsf/products?OpenPage&CollapseOutline=1

http://www.mercury.com/sales.nsf/products?OpenDocument&CollapseOutline=1

http://www.mercury.com/sales.nsf/products?OpenPage&CollapseOutline=1.2.3

http://www.mercury.com/sales.nsf/products?OpenDocument&CollapseOutline=1.2.3

ExpandOutline=[n]

Where n = the triangle at the first level of the outline. It is possible to expand a triangle in hierarchical
order. For example, &ExpandOutline=2.1.3 will expand the second triangle at the top level of the outline,
the first triangle at the second level, and the third triangle at the third level.

Syntax
http://Host/Database/PageName?OpenPage&ExpandOutline=n

http://Host/Database/PageUNID?OpenPage&ExpandOutline=n

Examples
These URLs do not point to existing Web sites. They are for example only.

http://www.mercury.com/sales.nsf/products?OpenPage&ExpandOutline=5

http://www.mercury.com/sales.nsf/products?OpenDocument&ExpandOutline=5

http://www.mercury.com/sales.nsf/35AE8FBFA573336A852563D100741784?OpenPage&
ExpandOutline=5.1.2

http://www.mercury.com/sales.nsf/35AE8FBFA573336A852563D100741784?OpenDocument&
ExpandOutline=5.1.2

Arguments
StartOutline=[n]

Where n is the triangle at the top level of the outline. It is possible to expand a triangle in hierarchical
order. For example, &StartOutline=2.1.3 will start the display with the third triangle at the third level of
the outline.

Syntax
http://Host/Database/PageName?OpenPage&StartOutline=n

http://Host/Database/PageUNID?OpenPage&StartOutline=n

516 Application Development with Domino Designer 7


Examples
http://www.mercury.com/sales.nsf/products?OpenPage&StartOutline=1

http://www.mercury.com/sales.nsf/products?OpenDocument&StartOutline=1

http://www.mercury.com/sales.nsf/35AE8FBFA573336A852563D100741784?OpenPage&
StartOutline=5.1.2

http://www.mercury.com/sales.nsf/35AE8FBFA573336A852563D100741784?OpenDocument&
StartOutline=5.1.2

URL commands for opening attachments, image files, and OLE objects
The following commands open files and objects within a document.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

OpenElement
Use the ?OpenElement command to access attachments, image files, and OLE objects.

Using OpenElement with attachments

Syntax
http://Host/Database/View/Document/$File/Filename?OpenElement

Example
http://www.mercury.com/lproducts.nsf/By+Part+Number/SN156/$File/spec.txt?OpenElement

Note: If more than one attached file has the same name, the URL includes both the ″internal″ file name
as well as the external name. Since the internal file name is not easily determined, make sure all attached
files have unique names.

Because some browsers require that the URL end with the attached file name, Domino treats all file
attachment OpenElement commands as implicit commands. For example:

http://Host/Database/View/Document/$File/InternalFileName/Filename?OpenElement

Using OpenElement with image files

Syntax
http://Host/Database/View/Document/FieldName/FieldOffset?OpenElement

http://Host/Database/View/Document/FieldName/FieldOffset?OpenElement&FieldElemFormat=
ImageFormat

Optional argument forOpenElement


FieldElemFormat = ImageFormat

Where ImageFormat is either .GIF or .JPEG. If you do not specify FieldElemFormat, Domino assumes the
image file format is .gif.

Chapter 28. Appendix E. URL commands for Web applications 517


Using OpenElement with OLE Objects

Syntax
http://Host/Database/View/Document/FieldName/FieldOffset/$OLEOBJINFO/FieldOffset/obj.ods?
OpenElement

Note: The current URL syntax for referencing images and objects in Notes documents -- specifically the
FieldOffset -- makes it impractical to create these URLs manually. As an alternative, you may paste the
actual bitmap or object in place of the reference, create URL references to files stored in the file system, or
attach the files to the documents.

URL commands for searching for text


Search-related URLs are available for performing view, multiple-database, and domain searches. Typically
you define a URL that displays an input form -- either a customized search form or the default search
form -- to let users define their own searches, but you may also define a URL that performs text searches
without user input. Both input and results forms may be customized.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

SearchDomain
Use SearchDomain URLs for text searches across a domain. The search input form is opened with the
OpenForm command by name or universal ID. For search results, the results template is specified as part
of the URL. If no template is found, then the default template form, $$SearchDomainTemplate, is
substituted. If $$SearchDomainTemplate is not found, an error is returned. If no results are returned, the
value of the $$ViewBody field remains the same.

Syntax
http://Host/Database/[templateForm]?SearchDomain[ArgumentList]

Where:
v templateForm is an optional argument that calls the search results form.
v ArgumentList is a list of optional arguments.

Example
http://www.mercury.com/mersrch.nsf/MercuryResults?SearchDomain

Redirect
The server will provide a direct or redirect URL command as needed for links displayed on the results
form if the capability has been enabled. The domain URL locates information on the server where the
links are generated. The redirect command locates the correct server and redirects a link to that server by
constructing the appropriate URL. The redirect command can improve performance by resolving
individual links when they are selected instead of resolving all of the links returned at once.

See Domino 5 Administration Help for information about enabling redirect on a server.

SearchSite
Use SearchSite URLs for text searches in multiple databases. Because the URL requires the name of a
search site database, be sure to create one before using a SearchSite URL.

518 Application Development with Domino Designer 7


Syntax
http://Host/Database/[$SearchForm]?SearchSite[ArgumentList]

Where:

$SearchForm and ArgumentList are optional arguments.

Example
http://www.mercury.com/mercsrch.nsf/$SearchForm?SearchSite

SearchView
Use SearchView URLs to limit a search to documents displayed in one database view.

This URL is useful for views that display all documents (so you can have a full-database search) or for
views in which you can predict what users need to see, such as all documents whose status is
″Completed.″

Syntax
http://Host/Database/View/[$SearchForm]?SearchView[ArgumentList]

Where:

$SearchForm and ArgumentList are optional arguments. The special identifier $SearchForm indicates that
Domino will present a search view form for search input. If this identifier is provided, the ArgumentList
is ignored. If this identifier is absent, a default form will be generated dynamically based on the contents
of the search.htm file located on the server. The default form generated by the server does not support
paged results.

Example
http://www.mercury.com/products.nsf/By+Product+Number/$SearchForm?SearchView

Optional arguments for SearchSite, SearchView, and SearchDomain


$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

The ArgumentList must contain the Query argument; in addition, it may contain any or all of the other
arguments in any order.

Query=string

Where string is the search string.

Count=[n]

Where n is the number of results to display on each page until the SearchMax has been reached. For
example Count=10 will display 10 results per page.

Scope=[1,2,3]

Chapter 28. Appendix E. URL commands for Web applications 519


The scope of the search. Where 1 = Notes databases only, 2 = file system only, 0 = both. The default value
is 0. This argument should only be used with the SearchDomain command.

SearchEntry=formName

Where formName is the name of the form to use for the results of a domain search. The default argument
is ″ResultEntry,″ which supports all of the predefined results fields specified in the ArgumentList. This
argument is valid for SearchDomain only and should not be used for SearchSite or SearchView.

SearchFuzzy=[TRUE,FALSE]

Indicate TRUE for fuzzy search. The default is FALSE.

SearchOrder=[1,2,3,4]

Indicate 1 to ″Sort by relevance,″ 2 to ″Sort by date ascending,″ 3 to ″Sort by date descending.″ The
default is 1. SearchView also supports a SearchOrder value of 4 to ″Keep current order,″ which sorts the
resulting set of documents in the order in which they appear in the view.

Note: Specifying SearchOrder=4 will produce unexpected results if:

The Count=n argument is used with a value less than the number of documents found The Start=n
argument is used with a value other than 1 The Default Search Limit is less than the number of
documents found The Max Search Limit is less than the number of documents found

If you need to specify SearchOrder=4, observe these recommendations:

Never specify Count=n or Start=n Always specify SearchMax=0 Set the Web site’s Max Search Limit to a
large value

SearchMax=[n]

Where n is the maximum number of entries returned. The default value is determined by the server.

SearchWV=[TRUE, FALSE]

Where TRUE = include word variants in the search. The default value is FALSE.

Start=[n]

Where n is the number corresponding to the document that appears first in your list of results. For
example, Start=10 begins your list of results with the 10th document found in the search. Start=0 means
that paged results will not be returned.

Examples
http://www.mercury.com/mercsrch.nsf/?SearchSite&Query=product+info+requests&SearchOrder=2&
SearchMax=30&SearchWV=TRUE&SearchEntry=″myResultsForm″

http://www.mercury.com/products.nsf/By+Product+Number/?SearchView&Query=PC156&
SearchOrder=3&SearchMax=1&SearchFuzzy=TRUE&SearchWV=FALSE

URL search syntax and customized results


The following parameters for SearchView and SearchSite URL commands allow you to display search
results page-by-page and to provide buttons or hotspots to navigate between pages.

520 Application Development with Domino Designer 7


Start and Count parameters
Start and Count parameters allow you to display search results page-by-page and may be included as
arguments in the SearchView or SearchSite URL commands or as items in the search results form. The
Start parameter is the entry that appears first when your results are displayed. The Count parameter is
the number of results that will display on each screen. For example, if Start=5 and Count=10, the search
results would display beginning with the 5th entry and would display up to 10 entries per screen until
the maximum number of entries has been displayed. These parameters work with customized forms only.

Syntax
http://Host/Database/ViewName/[$SearchForm]?SearchView[ArgumentList]

http://Host/Database/ViewUNID/[$SearchForm]?SearchView[ArgumentList]

Where: ArgumentList includes the Query argument and any or all of the other arguments including the
Start and Count parameters. For example:
?SearchView&Query=String&Start=n&Count=n&SearchOrder=n&SearchWV=TRUE or
FALSE&SearchFuzzy=TRUE or FALSE&SearchMax=n.

Examples
http://www.mercury.com/products.nsf/ProductView?SearchView&Query=bicycles&Start=21&Count=20&
SearchOrder=1&SearchWV=TRUE&SearchFuzzy=FALSE&SearchMax=50

http://www.mercury.com/products.nsf/F6025FD7E72456F985256540005839D3?SearchView&Query=
bicycles&Start=21&Count=20&SearchOrder=1&SearchWV=TRUE&SearchFuzzy=FALSE& SearchMax=50

Using Next and Previous buttons or hotspots with Start and Count
parameters
If you are using Start and Count parameters you can include Next and Previous buttons or hotspots to
enable users to navigate between pages of results. Both parameters must be used if you are using
navigational buttons.
1. Open your customized results form and place buttons or hotspots labeled Next and Previous where
you want them to appear on the form.
2. For the button or hotpsot labeled Next, write a formula that will advance the user forward one page.
3. For the button or hotspot labeled Previous, write a formula that will take the user back one page.

Example of a formula for a Next button or hotspot


@If(Hits >= Count; @URLOpen(″/″ + @Subset(@DbName; -1) + ″/″ + SearchView +
″?SearchView&Query=″ + @ReplaceSubstring(Query; ″ ″; ″+″) + ″&Start=″ + @Text(Start+Hits) +
″&Count=″ + @Text(Count) + ″&SearchOrder=″+@Text(SearchOrder) +″&SearchWV=″+@If(SearchVw =
0;″FALSE″;″TRUE″)+″&SearchThesaurus=″+@If(SearchThesaurus = 0;″FALSE″;″TRUE″) + ″&SearchMax=″
+ @Text(SearchMax)); ″″)

Example of a formula for a Previous button or hotspot


@If(Start > Count; @URLOpen(″/″ + @Subset(@DbName; -1) + ″/″ +SearchView + ″?SearchView&Query=″
+ @ReplaceSubstring(Query; ″ ″; ″+″) + ″&Start=″ + @Text(Start-Count) + ″&Count=″ + @Text(Count) +
″&SearchOrder=″+@Text(SearchOrder) +″&SearchWV=″+@If(SearchVw =
0;″FALSE″;″TRUE″)+″&SearchThesaurus=″+@If(SearchThesaurus = 0;″FALSE″;″TRUE″) + ″&SearchMax=″
+ @Text(SearchMax)); ″″)

Tip: To avoid syntax errors, use @ReplaceSubstring(Query; ″″ ’ ″+″) to replace all of the spaces in your
query with plus signs (+).

Chapter 28. Appendix E. URL commands for Web applications 521


URL commands for required 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 weren’t 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.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

Syntax
http://Host/DatabaseDirectory/DatabaseFileName?OpenDatabase&login

Examples
http://www.mercury.com/sales/leads.nsf?OpenDatabase&login

Logout command
You can specify a default logout time period to log the Web client off the server after a specified period
of inactivity. This forces the cookie that Domino uses to track the user session to expire. Automatically
logging a user off the server prevents others from using the Web client to impersonate a user if the user
leaves the workstation before logging off. If you enable session-based name-and-password authentication
for a server, users can also append ?logout at the end of a URL to log off a session.

Syntax
http://Host/DatabaseDirectory/DatabaseFileName?Logout

http://Host/DatabaseDirectory/DatabaseFileName?Logout&RedirectTo

Examples
http://acmeserver/sessions.nsf?logout
http://acmeserver/sessions.nsf?logout&redirectto=/logoutDB.nsf/logoutApp?Open
http://acmeserver/sessions.nsf?logout&redirectto=/logoutDB.nsf/logoutApp?
OpenPage
http://acmeserver/sessions.nsf?logout&redirectto=http://www.sales.com

You can build this expression into an application -- for example, using it in a button -- or type it in as a
URL.

URL commands for processing SSL certificates


The following commands automate the request and receipt of Secure Sockets Layer (SSL) certificates
stored in a database.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

OpenForm with SpecialAction argument

Syntax
http://Host/Database/FormName?OpenForm&SpecialAction=specialActionField

Where:

522 Application Development with Domino Designer 7


specialActionField is the name of an editable text field on the form whose value contains a predefined
command. To use the field with SSL certificates, use one of the following certificate request commands:

″SubmitCert″

″ServerRequest″

″ServerPickup″

For more information about the OpenForm command, see ″URL commands for opening agents, forms,
and navigators ″ earlier in this chapter.

Examples
http://www.mercury.com/certs.nsf/UserCertificateRequest?OpenForm&SpecialAction=SubmitCert

http://www.mercury.com/certs.nsf/ServerCertificateRequest?OpenForm&SpecialAction=ServerRequest

http://www.mercury.com/certs.nsf/Certificate?OpenForm&SpecialAction=ServerPickup

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:
v ResultForm is a form in the specified database that displays information about the processed request.
v 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:
v CommonName
v Org
v OrgUnit
v Locality
v State
v Country
v IssuerCommonName
v IssuerOrg
v IssuerOrgUnit
v IssuerLocality

Chapter 28. Appendix E. URL commands for Web applications 523


v IssuerState
v 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:
v ResultForm is a form in the specified database that displays information about the processed request in
the user’s browser after a successful submission.
v TranslationFormName represents a form in the database that contains fields to hold certificate
information.

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 in the document if the form contains fields with these names:
v CommonName
v Org
v OrgUnit
v Locality
v State
v Country

URL commands for setting user preferences in Web applications


In a Notes application, many settings -- such as how a date or time value is formatted or defaut language
preferences -- are set through a user’s operating system. Users can modify the settings according to their
preferences. In a Web application, the formats are determined by the settings that are installed with the
browser. The URL command OpenPreferences allows users of browser applications to select display
formats that apply to applications on one server or all the servers in a domain.

The OpenPreferences command works by setting a cookie for a user’s preferences. The server retrieves
the information from the user’s cookie and responds with the specified formats and preferences for that
user.

When designing an application, you might create a button that launches this URL command so that
browser users can set their preferences without having to enter the command themselves.

Note: The URLs shown below are for example only. They do not point to existing Web sites.

524 Application Development with Domino Designer 7


OpenPreferences

Syntax
http://Host/$Preferences.nsf?OpenPreferences[&Arguments]

OpenPreference with no arguments displays a frameset displaying a menu of choices on the left, and a
panel for selecting time zone preferences on the right. OpenPreferences accepts arguments for
manipulating what preference page displays.

The Host argument can apply to the server named or to all of the servers in the domain of the specified
server. The scope of OpenPreference is determined by the value in the Web User Preferences field on the
Web Site Template for the specified server. If the Web User Preferences field is set to Multi-server, the
settings for OpenPreference apply to all of the servers in the domain. If the field value is Single server,
the preferences apply only to the specified server. The server administrator can also set the field to
Disable, which causes the server to ignore any cookies set for OpenPreference. Speak to your system
administrator about setting the correct scope for the command.

Note: Settings a user specifies for OpenPreferences will not override custom settings you specify for a
field or view column.

Examples
http://www.mercury.com/$Preferences.nsf?OpenPreferences

Optional arguments for OpenPreferences


The following arguments open specific pages of the OpenPreferences user interface instead of loading the
default frameset.

&PreferenceType=Menu

Displays only the Menu page, with links for opening the Time Zone and Regional preference pages.

&PreferenceType=Time Zone

Displays only the Time Zone selection page. The defaults dispayed are the server settings. Users can
either select custom settings and apply them by clicking the Custom button, or click the Server button to
apply the server settings as their preferences.

Chapter 28. Appendix E. URL commands for Web applications 525


&PreferenceType=Regional

Displays only the Regional preference page. Regional settings apply to Date/Time and Number/Currency
settings. When the page first opens, the default for the ″Preferred Locale″ field is derived from the Accept
Language setting for the user’s browser. The other configuration items are based on the browser defaults
that correspond with the language setting. A user can specify a new value for ″Preferred Locale″ and
click the ″Load default options for this locale″ button to apply all of the formats that correspond with the
specified locale. A user can set new preferences or revert to the defaults.

526 Application Development with Domino Designer 7


Managing multilingual input in a single database
The charset=[MIME charset name] argument can be added to any URL command to return the requested
form or page in the specified character set, regardless of the preferred language setting in the browser.
The server does not generate the charset=[MIME charset name] argument automatically. It must be built
into the application.

Syntax
http://Host/Database/FormName?OpenForm&charset=[MIME charset name]

Where:
v FormName is the name of the form to be opened.
v [MIME charset name] is the name of the character set that will be used for the returned target form.

Usage
The charset=[MIME charset name] argument will override the $$HTMLContentLang field in a form. For
information on using the $$HTMLContentLang field to enable multiple character sets to be used for input
to a database see the topic ″Managing multilingual input in a single database″ in Lotus Notes, Domino and
Designer Release Notes -- Release 5.0.2.

Example
A company has sales staff in the United States, Japan, and Russia. Members of each staff are expected to
submit performance summaries monthly to a single database. The sales personnel can use English,
Japanese, and Russian character sets in the same database if the URL command that returns the summary

Chapter 28. Appendix E. URL commands for Web applications 527


form uses the charset=[MIME charset name] argument. When the server receives the command, it returns
the target form in the specified character set. A URL command that would return the target form in the
Japanese character set is shown below.

http://www.mercury.com/sales.nsf/Summary?OpenForm&charset=Shift_JIS

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 server’s
PATH statement for a Perl interpreter named perl.exe. To override this default, define an environment
variable (PERLBIN) that gives the name or absolute path of the perl interpreter -- for example,
c:\perl5\bin\perl.exe.

Common Gateway Interface (CGI) programs


CGI is a standard for connecting external applications with HTTP servers. CGI programs allow you to do
some background 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 specify when you
want to use the Notes API to further process the data. To run a CGI program this way, add a field named
$$Return, and use HTML instructions as the field value.

CGI variables
When a Web user saves a document or opens an existing document, the Domino Web server uses CGI
variables to collect information about the user, including the user’s name, the browser, and the user’s
Internet Protocol (IP) address.

To capture this information in a Web application:


v Create a field with the name of a CGI variable.
v Create an agent whose script contains a CGI variable as a DocumentContext property.

Creating a field with the name of the CGI variable


When a field is named after a CGI variable, Domino copies the field value from the CGI environment
and places it in the field. This feature is useful in computed-for-display fields and for determining ″hide
when″ conditions.
1. Create a field and give it the name of a CGI variable.
For example, to obtain the IP address of the user submitting the form, add a field named
Remote_Addr to the form.
2. Select the hide-when field properties ″Previewed for Editing″ and ″Opened for editing″ so users
cannot enter information in it.

528 Application Development with Domino Designer 7


Table of CGI variable names
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_Accept_language The languages 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.
HTTPS_CLIENT_CERT_COMMON_NAME The common name on the x.509 certificate
HTTPS_CLIENT_CERT_ISSUER_COMMON_NAME The issuer of the x.509 certificate
HTTPS_KEYSIZE The session key during an SSL session. For example,
40-bit, 128-bit.
HTTP_User_Agent The browser that the client is using to send the request.
Path_Info The extra path information (from the server’s 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_Info_Decoded Returns the same as Path_Info, but decodes the string.
For example, if a URL references a view name that
contains characters that are not allowed a URL, the name
is encoded. This CGI variable decodes the string.
Path_Info_Decoded is available to Domino applications
only.
Path_Translated The server provides a translated version of PATH_INFO,
which takes the path and does any virtual-to-physical
mapping to it.

Chapter 28. Appendix E. URL commands for Web applications 529


Field name Returns
Query_String The information that follows the question mark (?) in the
URL that referenced this script.
Note: If your Domino server is configured to allow
search engines to search your Web site Domino will
generate URLs with an exclamation mark (!) instead of a
question mark (?). If this is the case the Query_String
CGI variable includes the information that follows the
exclamation mark (!). Domino always recognizes both the
question mark (?) and the exclamation mark (!), but only
generates URLs with the exclamation mark (!) if your site
is accessible to Web search engines. Generating URLs
with an exclamation mark (!) makes them more
searchable.
Query_String_Decoded Returns the same as Query_String, but decodes the
string. For example, if a URL references a view name
that contains characters that are not allowed in a URL,
the name is encoded. This CGI variable decodes that
string. Path_Info_Decoded is available to Domino
applications only.
Remote_Addr The IP address of the remote host making the request.
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_Content Supported only for agents. Contains the data sent with
an HTTP POST request. The data is usually
″URLencoded,″ consisting of name=value pairs
concatenated by ampersands. For example,
FirstName=John&LastName=Doe
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 server’s 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.

530 Application Development with Domino Designer 7


Appendix F. Accessibility and Keyboard Shortcuts
This appendix provides information regarding designing applications for maximum accessibility for users
with physical challenges.

Accessibility and keyboard shortcuts


Domino Designer is accessible to people with physical challenges. Those with restricted mobility or
limited vision can use the following assistive aids:
v Extended accelerator keys let you navigate through the Bookmark bar and window tabs using your
keyboard. Note that you must enable extended accelerator keys before you can use them.
v Keyboard shortcuts let you navigate through and perform a variety of tasks in Designer.

For more information about accessibility, see:


v The topic ″Customizing Notes for Accessibility″ in Lotus Notes Help.If the Help is not installed, you
can go to the Documentation Library of the Lotus Developer Domain at
http://www.lotus.com/ldd/doc to download or view Lotus Notes Help.
v The IBM Special Needs Web site at http://www.ibm.com/able.

Enabling and using extended accelerator keys


Before you can use extended accelerator keys to navigate through the Bookmark bar or the window tabs,
you must enable the keys.

To enable extended accelerators for the Bookmark bar


1. Choose File - Preferences - User Preferences.
2. Select Basics.
3. In the Additional Options box, select ″Show extended accelerators.″

To use extended accelerators in the Bookmark bar


Once you enable extended accelerators, press ALT+B to display them on the Bookmark bar.

You can use the accelerator keys as follows:


v To navigate, use the UP and DOWN ARROWS, and HOME, END, PAGE UP, and PAGE DOWN.
v To select a Bookmark icon, press ENTER.
v To remove focus on a Bookmark icon, press ESC.

To enable keyboard navigation of window tabs


1. Choose File - Preferences - User Preferences.
2. Select Basics.
3. In the Additional Options box, select ″Show extended accelerators.″

To use extended accelerators in window tabs


To use an accelerator, press ALT+W, followed by the number that appears next to the window tab.

531
Keyboard shortcuts
The keyboard shortcuts in this section are based on U.S. standard keyboards. If you are using a screen
reader, you may want to maximize your window so the tables of shortcuts are completely expanded and
accessible.

Click these links to see shortcuts for:


v Changing text and paragraph properties in a document
v Databases
v Designer interface and windows
v Dialog boxes
v Moving the cursor in a document
v Navigating through views, folders, and panes
v Properties boxes
v Reading documents
v Selecting and moving text in a document
v Working in views

Keyboard shortcuts for the Designer interface and windows


You can use the following keyboard shortcuts to navigate through Designer.

Press To do this
ALT+B, then number (extended accelerators in User Open bookmark on Bookmark bar
Preferences must be enabled)
ALT+F5 Restore Designer to default minimized size
ALT+F7, then ARROW KEYS, then ENTER Move position of active window
ALT+F8, then ARROW KEYS, then ENTER Change size of active window
ALT+F9 Minimize active window
ALT+F10 Maximize active windows
ALT+underlined letter for menu item Access menu item
ALT+underlined letter for menu item, or ARROW KEYS Move to next menu item
ALT+W, then number (extended accelerators in User Open window tab on task bar
Preferences must be enabled)
CTRL+BREAK Stop operation in progress
CTRL+L, type URL, then ENTER Go to a Web page
CTRL+Q or ALT+F4 Exit Designer
CTRL+TAB Move to next window tab
ESC or CTRL+W Close active window
F1 Get Help on current feature
F5 Lock User ID
F6 Move to next pane or frame
F10 or ALT Access menu bar
SHIFT+ALT+S Open search menu
SHIFT+CTRL+TAB Move to previous window tab
SHIFT+CTRL, then UP ARROW or DOWN ARROW Select multiple bookmarks or Bookmark folders

532 Application Development with Domino Designer 7


Press To do this
SHIFT+DOWN ARROW Select additional items below an already selected item
SHIFT+F6 Move to previous pane or frame
SHIFT+F10 Access Windows context menus
SHIFT+UP ARROW Select additional items above an already selected item

Keyboard shortcuts for databases


You can use the following keyboard shortcuts for getting to and navigating through a database.

Note: In any form, page, or document there could be several embedded elements (the date picker in the
Calendar is an example of an embedded element). You can navigate to an embedded element, give focus
within the embedded element, and then remove the focus to continue navigating through the form, page,
or document. When focus is in an embedded element, the thin black frame around it disappears. When
focus is removed from an embedded element, the thin black frame reappears.

Press To do this
ARROW KEYS Move through embedded element
CTRL+N Create new database
CTRL+O Open database
ENTER Select item in embedded outline
ESC Exit embedded element
ESC or CTRL+W Close current database
F9 Refresh current document (in Edit mode), view or workspace
MINUS (-) key Collapse folder in embedded outline
PAGE DOWN Move to bottom of active page
PAGE UP Move to top of active page
PLUS (+) key Expand folder in embedded outline
SHIFT+CTRL+F9 Update all views in current database
SHIFT+F9 Rebuild current document, view, workspace (must have Manager access)
SPACEBAR Give focus to embedded element
UP and DOWN ARROW Move through embedded outline

Keyboard shortcuts for dialog boxes


Standard dialog boxes appear when you perform many tasks in Designer. For example, the Open
Database dialog box appears when you choose File - Database - Open from the menu.

Press To do this
DOWN ARROW or RIGHT ARROW Select next item in a list or set of options in dialog box
ESC Cancel changes and close dialog box
F1 Get Help on current dialog box
SHIFT+TAB Move to previous option or set of options in dialog box
SPACEBAR Access default or selected item(s) in dialog box
TAB Move to next option or set of options in dialog box

Chapter 29. Appendix F. Accessibility and Keyboard Shortcuts 533


Press To do this
UP ARROW or LEFT ARROW Select previous item in a list or set of options in dialog box

Keyboard shortcuts for properties boxes


In Designer, you can learn about and change the characteristics of a document, object, or database by
opening what’s known as a properties box. For example, when you’re editing a document, choose Text -
Text Properties from the menu to open the Text Properties box.

Press To do this
ALT+DOWN ARROW Open Color box in Font tab
ALT+UP ARROW Close Color box in Font tab
ALT+ENTER Open or close properties box
CTRL+ALT+ENTER Open or close express tools in properties box
CTRL+END Move to last properties box tab
CTRL+HOME Move to first properties box tab
CTRL+PAGE DOWN Move to next properties box tab
CTRL+PAGE UP Move to previous properties box tab
DOWN ARROW or RIGHT ARROW Select next item in a list or set of options in properties box
ENTER Activate default or selected item(s) in properties box
ENTER Close Color box in Font tab and activate selection
ESC Close Color box in Font tab without activating selection
F1 Get Help on current properties box
SHIFT+CTRL+END Move to first properties box in list
SHIFT+CTRL+HOME Move to last properties box in list
SHIFT+CTRL+PAGE DOWN Move to next properties box in list
SHIFT+CTRL+PAGE UP Move to previous properties box in list
SHIFT+TAB Move to previous option or set of options in properties box
TAB Move to next option or set of options in properties box
UP ARROW or LEFT ARROW Select previous item in a list or set of options in properties box

Keyboard shortcuts for documents


You can use the following keyboard shortcuts when you are in a document.

Press To do this
CTRL+DOWN ARROW Move to next highlighted search word in document appearing in
preview pane
CTRL+E Edit document
CTRL+END Move to bottom of document
CTRL+F Find text and replace
CTRL+G Find next occurrence of text
CTRL+HOME Move to top of document
CTRL+P Print selected document

534 Application Development with Domino Designer 7


Press To do this
CTRL+PAGE DOWN Move to next tab in tabbed table
CTRL+PAGE UP Move to previous tab in tabbed table
CTRL+UP ARROW Move to previous highlighted search word in document appearing in
preview pane
ESC Move to previous linked document
F4 or TAB Move to next unread document
LEFT ARROW Move to previous link or object
RIGHT ARROW Move to next link or object
SPACEBAR Activate selected object
SPACEBAR Expand or collapse selected section
SPACEBAR Open selected link to document, view or database

Keyboard shortcuts to select and move text in a document


You can use the following keyboard shortcuts when you are creating or editing a Mail memo, a
document, or form. You must be in Edit mode to use these shortcuts. Press CTRL+E to put your
document in Edit mode.

Press To do this
CTRL+A Select all contents of document
CTRL+C Copy selected text or object
CTRL+DOWN ARROW Move item in list or table one row down
CTRL+UP ARROW Move item in list or table one row up
CTRL+V Paste text or object
CTRL+X Cut selected text or object
DELETE Delete selected graphic
DELETE Delete selected text or object
SHIFT+CTRL+DOWN ARROW Select text up to same point of next line
SHIFT+CTRL+LEFT ARROW Select previous word
SHIFT+CTRL+RIGHT ARROW Select next word
SHIFT+CTRL+UP ARROW Select text up to same point of previous line
SHIFT+DOWN ARROW Select text to end of current line, move focus to next
SHIFT+END Select text to end of current line
SHIFT+HOME Select text to beginning of current line
SHIFT+LEFT ARROW Select previous character
SHIFT+RIGHT ARROW Select next character
SHIFT+UP ARROW Select text to beginning of current line, move focus to previous

Chapter 29. Appendix F. Accessibility and Keyboard Shortcuts 535


Keyboard shortcuts to move the cursor in a document
You can use the following keyboard shortcuts when you are creating or editing a Mail memo, a
document, or form. You must be in Edit mode to use these shortcuts. Press CTRL+E to put your
document in Edit mode.

Press To move to
CTRL+LEFT ARROW Beginning of current word
CTRL+RIGHT ARROW Beginning of next word
END End of line
HOME Beginning of line
SHIFT+TAB Previous field in a form
SHIFT+TAB Previous row in table
TAB Next field in a form
TAB Next row in table

Keyboard shortcuts to change text and paragraph properties in a


document
You can use the following keyboard shortcuts when you are creating or editing a Mail memo, a
document, or form. You must be in Edit mode to use these shortcuts. Press CTRL+E to put your
document in Edit mode.

Press To do this
CTRL+B Bold selected text
CTRL+E Put document in Edit mode (toggle)
CTRL+F Find text and replace
CTRL+G Find next
CTRL+I Italicize selected text
CTRL+J Format paragraphs (alignment, spacing, etc.)
CTRL+K Format text (font, size, color, etc.)
CTRL+R Show/Hide ruler
CTRL+T Change text style to default (color changes only if the text style is from a Paragraph Style)
CTRL+U Underline selected text
CTRL+Z Undo last action
F2 Enlarge selected text to next available point size
F7 Indent first line in paragraph
F8 Indent entire paragraph
F9 Refresh current document (in Edit mode), view, or workspace
F11 Cycle through paragraph styles from Paragraph Styles tab in Text Properties box
SHIFT+CTRL+L Insert page break
SHIFT+F2 Reduce selected text to next available point size
SHIFT+F7 Outdent first line in a paragraph
SHIFT+F8 Outdent entire paragraph

536 Application Development with Domino Designer 7


Keyboard shortcuts to navigate within views, folders, and panes
You can use the following keyboard shortcuts to navigate through a view, folder, or pane.

Note: In any view, folder, or pane, there can be several embedded elements (the date picker in the
Calendar is an example of an embedded element). You can navigate to any embedded element, give focus
within the embedded element, and then remove the focus to continue navigating through the view,
folder, or pane. When focus is in an embedded element, the thin black frame around it disappears. When
focus is removed from an embedded element, the thin black frame reappears.

Press To do
ARROW KEYS Move between views and folders
ARROW KEYS Move through embedded view
ASTERISK (*) key on numeric keypad Expand collapsed view, category, or folder with subsections
BACKSPACE Open previous document in current view or folder
CTRL+END Move to bottom of navigation pane or view pane
CTRL+HOME Move to top of view navigation pane or view pane
END Move to far right of view pane
ENTER Open next document in current view or folder
ENTER Open selected view or folder
F6 Move to next pane or frame
HOME Move to far left of view pane
MINUS (-) key Collapse expanded view, category, or folder
PLUS (+) key Expand collapsed view, category, or folder
SHIFT+8 Expand all collapsed views, categories, or folders with subsections
SHIFT+BACKSPACE Select previous document in view
SHIFT+F6 Move to previous pane or frame
TAB Move to next unread document in embedded view

Keyboard shortcuts when working in views


You can use the following keyboard shortcuts when you are in a view.

Note: In any view, there can be several embedded elements (the date picker in the Calendar is an
example of an embedded element). You can navigate to any embedded element, give focus within the
embedded element, and then remove the focus to continue navigating through the view. When focus is in
an embedded element, the thin black frame around it disappears. When focus is removed from an
embedded element, the thin black frame reappears.

Press To do this
CTRL+A Select all documents in view
CTRL+C Copy selected document
CTRL+F Find text in view
CTRL+P Print selected document or view
CTRL+V Paste selected document
CTRL+X Cut selected document
DELETE Delete selected document (place document in Trash folder)

Chapter 29. Appendix F. Accessibility and Keyboard Shortcuts 537


Press To do this
ENTER Select item in embedded view
F3 Move to next selected document
F4 or TAB Move to next unread document
F9 Refresh current document (in Edit mode), view or workspace
SHIFT+CTRL+F9 Update all views in current database
SHIFT+DELETE Delete selected document permanently
SHIFT+F3 Move to previous selected document
SHIFT+F9 Rebuild current document, view, or workspace (must have Manager access,
or for server databases, Editor access with ″Create shared folders/views″
selected)
SPACEBAR Select or deselect document

538 Application Development with Domino Designer 7


Index
Special characters About Database document (continued)
inheriting from template 420
Action bar
described 242
$$fields launching 418 Action bar applet
list of 142, 415 opening 505 described 25, 242
$$HTMLHead field 142 Accelerator keys. See Shortcut keys 531 Actions
$$NavigatorBody field 142 Access built-in 236
$$Return field 105, 142 denying 373, 393 copying 240
$$ReturnAuthenticationFailure field 105 Access control list. See ACL 365 creating 240
$$ReturnAuthorizationFailure field 105 Access level privileges creating hotspots for 236
$$ReturnDocumentDeleted field 105 ACL 368 deleting 240
$$ReturnGeneralError field 105 Access levels described 11, 236
$$ViewBody field 142, 518 anonymous 373 editing 244
$$ViewList field 142 assigning 365 examples 236
$Anonymous field 386 conflicts 380 icons for 240, 244
$ChargeRead field 142 default 372 in Notes and Web applications 18
$ChargeWrite field 142 editing 372 inserting 244
$fields list of 411 naming 274
$Anonymous 386 Accessibility navigator 224
$HLFormula 131 additional information about 531 OLE and 337
$PublicAccess 391 custom tools and 277 publishing 327
$Title 77 customizing settings for 531 shared 38, 244
$UpdatedBy 386 for users with disabilities 25 simple 235
$VersionOpt 145 of navigators 224 URL commands and 503
$GroupScheduleRefreshMode field 142 of outlines 214 Web 496
$GroupScheduleShowLegend field 142 of view icons 178 Actions field
$HLFormula field 131 ACL described 415
$PublicAccess field 391 access for Web users 380 Actions menu
$Title field 77, 142, 143 access level privileges 365, 368 described 240
$trash access levels 366, 411 Actions with children
creating a trash folder 205 agent security and 257 creating 240
$UpdatedBy field 386 aliases in 373 ActiveX controls
$VersionOpt field 142, 145 anonymous access 373 debugging 329
@commands brackets in 370 defined 327
for application automation 272 CGI and 528 Administration Process
on Web 22 concurrent changes to 460 setting up for databases 387
Programmer’s pane and 3 consistency 468 Administration servers
referencing 133 copying from template 33 assigning to databases 387
@Db commands default entries 372, 382 Agent Log
@DbColumn 128, 291 ECL and 365 described 263
@DbCommand 291 editing 372 size limit 265
@DbLookup 128, 291 effective access and 380 Agent Manager
described 283 enforcing on replicas 379 described 237
@DbName function 211 entering names 128 recording less information 264
formula language 211 format for entries 373 setting up debugging 261
@functions group names 372, 373, 382 Agents, types of
for date and time calculations 123 LDAP users and 373 background or foreground 257
for external data access 128 monitoring 380 built-in 237
Programmer’s pane and 3 order of evaluation for entries 373 embedded 257
referencing 133 replica IDs 373 Java and LotusScript 257
Web 495 replication and 468 local or server 257
@IsDB2 function 211 roles 370 public access 391
server names 373 Agents, uses for
setting up 365 adding fields with 415
Numerics terminations group 373 editing documents with 415
1-2-3 files troubleshooting 468 generating XML with 321
importing into views 482 URL commands and 522 hiding design with 431
user names 373 in Notes and Web applications 18
user types 378 mail 346
A using to enter names 125
Web previewing and 46
mail responses 346
removing field data with 415
About Database document wildcard entries 373 removing stored forms with 415
creating 404

539
Agents, uses for (continued) Applets (continued) Backgrounds
renaming fields 415 outline 223 for pages and forms 60
resaving documents with 415 view 200 Billing
Agents, working with Web applications and 25 forms for 101
Agent Manager debugging 264 Application design elements reserved fields for 142
calling 240 security 383 Bitmap files. See Graphics 59
chaining together 266 Applications BlindCopyTo field 143
compared to servlets and CGI annotating 407 BMP files. See Graphics 226
programs 307 automating 235, 337 Body field 141
copying 254 completing 403 described 415
creating 250, 368 creating bookmarks 35 Bold text
debugger settings 263 deploying 408 in Web applications 118
debugging 261 design tips 17 Bookmark bar
deleting 254 documenting 404 creating bookmarks on 35
described 11, 237 for mobile clients 23 creating link to databases 35
disabling 254 mail-enabled 343 enabling keyboard navigation 531
enabling 253 managing 435 Bookmarks
examples 256 master design copies 408 organizing applications 35
invoking 307 overview of Domino 1 using 35
naming 274 planning 17 Borders
profiling 262 planning for Notes and Web 17 for embedded elements 62
renaming 413 previewing 46 for frames 149
restricted operations for LotusScript setting launch properties for 418 Browsers
and Java 270 testing 412 designing applications for 17
restricting 368 Archives, database differences 18
run-time statistics 263 creating 456 hiding paragraphs from 137
running 240 Arguments launch options 418
security for 257, 307 setting for Java applets 295 proxy settings for 46
simulating a run 261 Attachments setting up for previewing 46
triggering 251, 253 creating 61, 93 using Print statement to instruct 269
viewing 237 opening with URL commands 517 using with Notes client 118
viewing the log 263 Attributes Buddy lists
Web and 496 HTML 139 embedding 63
Aliases Authentication Button bar
choice list 129 for Web users 373 described 242
converting to full names 129 URL commands and 522 Buttons
form names 80 user names 373 creating 22, 246
in ACL 373 Author access customizing icon 37
servlet names 309 actions 366 defined 236
Alternate HTML privileges 368 deleting 246
described 297 Authors editing 246
Alternate names anonymous 83
in ACL 373 Authors field
Alternate text tag
for images and Java applets 25
creating 385
described 384
C
CAB files
Annotating restricting read-access with 384
described 294
applications 407 updating 386
Calculating
documents 88 Autolaunching
cell values 183
fields 406 defined 332
field values 120
Anonymity objects 327, 333
Calendar controls
protecting 83 Automating
adding to a page or form 62
Anonymous access level applications 235, 337
creating 124
in ACL 373 described 11, 235
Web use of 496
Anonymous field formulas for 272
Calendar views
on forms 386 hiding components 275
creating 193, 496
Anonymous forms JavaScript and 273
defined 155
creating 83 navigators 228
described 157
AppletBase replies 346
formatting 193
extending 300 security features and 272
using with the embedded
Applets using LotusScript 269
scheduler 93
action bar 242 Averages
Cascading
adding to a page or form 61 calculating 183
form names 80
creating 242
Cascading Style Sheet. See CSS 24
described 307
Categories
editor 118
font support and 200
B adding to views 186
Background processing columns 187
listed 25
on Web pages 528 field for creating 142, 187

540 Application Development with Domino Designer 7


Categories (continued) Colors (continued) Connectivity
generating dynamically 187 for Web applications 22 for relational databases 284
naming 187 unread marks and 190 Console commands
user-created 186 Column descriptor file. See COL described 263
Category fields files 486 Contact lists
described 187 Column width embedding 63
cc:ing. See Mail 344 described 486 Contact printing
cc:Mail Columns example 101
mailing to 143 adding to views 159 forms for 101
CD-ROM updates calculating values in 183 reserved fields for 101
replication and 442 categorized 186 Controls
Certificates copying 159 date/time 124
SSL 522 creating 167 embedded 93
CGI date 170 Cookies
defined 528 deleting 159, 167 programming for 307
CGI programs displaying custom icons 178 Copy Java applet
compared to servlets and agents 307 entering names from 128 described 299
invoking 307 for Web links 172 CopyTo field 143
security for 307 formatting 170 CORBA properties
CGI variables hide-when formulas and 172 for Java applets 297
fields and 528 hiding 182, 183 CORBA SSL security
table of 529 icons in 178 for Java applets 297
user profiles and 528 mapping to fields in views 484 Count parameter
Character translation file numbers 171 Domino URL commands and 518
described 481 programmatic name for 172 search results and 521
Check box fields programming 173 Create menu
aliases in 129 response 189 documents and 80
Checkbox fields setting styles for 169 CreateDocument command
in Web applications 497 specifying data type in views 484 described 512
Choice list fields styling 183 CSS
aliases in 129 switching to a view 183 class and objects 24
creating 127 testing 410 defined 316
refreshing 135 time 170 passing information 142
views and 100 titles for 168 shared resources and 70
Choices views and 9, 155 styles applied to objects 24
displaying in lists 100, 127 width 183, 486 supported properties 70
refreshing 135 Combo box fields XML 315, 317
Class name aliases in 129 CSV format
described 294 described 127 for exporting views 487
CLS files Command keys Currency
described 481 defined 531 fields for 120
CodeBase property Common Gateway Interface. See formatting 120, 171
for Java applets 297 CGI 528 Custom controls
COL files Common name adding to forms 328
creating 484 displaying 125 described 327
defined 484 Compatibility running in Read mode 331
formulas and 484, 487 and views 203 sizing 330
guidelines 484 Compatibility with earlier releases. See updating 331
importing a tabular text file 486 Upgrading 293 Customize subform
keywords 485 Components using 359
Collapsing sizing 330 Customizing
sections 387 using 327 column sorting 182
views 183 ComposedDate field 141 databases 31
Color fields Computed fields icon buttons 37
described 132 CGI programs and 528 letterheads 41
Color palettes defined 133 templates 420
blending colors 41 order of evaluation 80 window titles 88
changing 22 Computed for display fields 133
choosing colors 58 Computed text
Colors
blending 41
described 53
Computed when composed fields 133
D
Data access
for columns 183 Configuring
with @DbColumn and
for frame borders 149 offline applications 351
@DbLookup 128
for navigators 227 Conflict documents. See Replication
with Domino Connectors 283
for outline entries 218 conflicts 83
with Lotus Enterprise Integrator 283
for rows 183 Connections
with ODBC 290
for views 183 enabling for a database 288
with servlets 307

Index 541
Data Connection Resources. See Databases (continued) Debug_AMgr statement
DCRs 283 replicating 438, 446 described 264
Data entry replication history 458 DEBUG_OUTFILE statement
fields for 133 replication log 459 described 264
Data types response forms 85 Debugging
defined 113 restricting creation of 257 agents 261
list of 116 roles 370 Java applets 304
listed for choice list fields 127 rolling out 435 NotesLog class 265
Database access security 365, 378 Decimal places
access level conflicts 380 shared resources across 38 in Number fields 120
troubleshooting 464 shortcut keys 533 Decimal symbol
Database activity size 461 described 120
monitoring 461 size limits 437 Decrypting documents
reporting 463 size, controlling 454 overview 395
statistics 462 statistics 461 DECS
Database analysis summary 413 described 283
of replication events 458 synchronizing 424 Default field values
Database cache templates 424 for editable fields 134
performance problems and 465 titles for 31 Default group
Database creator troubleshooting 464 access level 372
access level 372 unlinking 429 DeleteDocument command
Database design unlocking design elements in 432 described 512
changing 425 URL commands and 505 Deletion stubs
replicating 467 Datalens purging 440, 469
templates and 31 ODBC and 290 DeliveryPriority field 143
Database icons Date picker DeliveryReport field 143
creating 403 adding to a page or form 62 Deploying
replacing 428 in Web applications 496 applications 408
Database libraries Date separator Depositor access
design library template 422 described 121 actions 366
Database performance Date/Time controls privileges 368
troubleshooting 461, 464, 465 described 124 Design
Database properties Date/Time fields changing 429
for enabling connectivity 288 described 121 hiding 33, 431
Database titles Date/Time formats linking 423
replicating 467 setting for Web applications 524 maintaining 411
Databases Dates preventing changes 408
access control lists 383 displaying 170 refreshing 426
access control log 373 entering 121, 124 replacing 428
access problems 464 formatting 121, 170 replication and 429
administration servers and 387 formula language 123 templates and 419, 429
as external data sources 286 ranges 121 updating 426
connecting to 283, 284 DAV. See DB2 access view. 471 Design action buttons
controlling access to 365 DB2 described 3
copying to servers 435, 437 connecting to 287 Design changes
creating 31, 423 integrating with 21 making 425
creating bookmarks to 35 DB2 access view 471 templates and 31
defined 1 creating 473 Design elements
documenting 404 managing 475 automating 250
editing with WebDAV 278 security 472 copying 36, 422
encrypting 393, 438 troubleshooting 476 hiding 432
external 290 DB2 query view library of 422
forcing replication 447 @ functions 211 linking 424
hiding 432 creating 208 listed 1
icons 403 managing 210 locking 432
importing external records from 289 DB2 query views 207 multiple selection of 430
Internet security 381 DCRs previewing 46
launching 152, 418 creating 286 protecting 429
linking 423 customizing 287 templates and 424
locking design elements in 432 data sources and 286 unlinking 429
mail features and 345 described 283 unlocking 432
managing 435 enabling 288 updating 426
monitoring 380 fields and 288 Design library template
moving 464 importing external records 289 described 422
previewing 418 overview of 285 Design properties
renaming 413 specifying default 288 setting for multiple elements 430
replacing design of 428 using on forms 288

542 Application Development with Domino Designer 7


Design synopsis Documents (continued) Duration controls
creating 413 response 85 creating 124
Designer saving 143 in Web applications 496
starting 2 security 257, 383, 384, 390, 395 setting separator for 138
third-party tools and 277 selecting in Web applications 203 DXL
work area overview 3 shortcut keys 534 described 313
Designer access signing 388, 401 transforming 324
actions 366 storing forms with 142, 143
privileges 368 summary of 266
Designer task
updating databases with 424
tracking 101
tracking versions 86
E
E-mail. See Mail 344
Dialog boxes unread 190
ECL
and Web applications 18 updating 414, 415
described 365
creating 98, 99 Web and 80, 512
setting up for secure Java applet
designing in formula language 99 Documents, mailing 266, 344
access 300
shortcut keys 533 DOLMKINF utility
Edit mode
Dialog forms creating filesets with 358
for forms and documents 83
described 99 DOLRES.NTF
hidden data in 23
Dialog list field copying design elements from 349
Editable fields
described 127 DOLS. See Domino Off-Line
defined 133
Directory catalogs Services 349
EditDocument command
offline 362 Domains
described 512
offline applications and 362 searching 518
Editing
Discussion template Domino
concurrent 460, 469
described 31, 479 security 365
documents 415
Disk space Domino Connectors
fields 390
saving 368 described 283
forms 414
DocBase property Domino Directory
images with the editor applet 498
for Java applets 297 accessing 492
navigators 225
Document archiving tool entering names 128
restricting 384
described 456 offline 362
URL commands and 512
Document keys Domino Directory Server document
window titles 88
opening documents with 514 servlet manager settings 309
Editor access
Document Library template Domino Enterprise Connection Services.
actions 366
described 479 See DECS 283
privileges 368
Documenting Domino Global Workbench
Editor applet
applications 404 described 27
described 25
databases 404 Language Synchronizer 27
using 118
fields 406 Domino Java Virtual Machine (JVM) 309
Editors
Documents Domino Off-Line Services
anonymous 83
accessing 77, 383 described 349
embedding in a form 96
annotating 88 design elements 359
sections and 387
anonymous 83 developer tasks 349
tracking 386
archiving 456 forms 349
Effective access. See ACL 380
conflict 83 installing 350
Embedded controls
copying 33, 266 overview 349
date picker 62
creating 80, 512 replicating databases 357
embedded scheduler 93
decrypting 394, 395 URLs and 357
file upload control 93
deleting 266, 512 Domino security
forms and 93
deleting from views 205 application design elements 383
group scheduler 496
displaying 319 Domino URL commands
Embedded editors
editing 406, 415, 460, 512 authentication and 522
creating for a form 96
encrypting 394, 395, 399 count parameter 518
Embedded elements
footers 83 explicit 514
borders for 62
forms and 77 implicit 514
contact lists 63
headers 83 opening documents by key 514
embedded scheduler 93
hiding 335 server commands 505
keyboard accessibility and 25
launching 404 ServerRequest 522
pages and 62
launching into framesets 152 start parameters 518
reserved fields for 142
linking in workflow applications 344 syntax 503
Embedded objects
locking/unlocking 45 Domino-generated fields. See Reserved
autolaunching 333
modifying 139 fields 386
Embedded scheduler
moving 266 DominoObject
using 93
opening 514 in URL commands 503
Embedded views
previewing 418 DTD
setting display properties 198
read/unread status 190, 266 defined 316
Embedding
replication conflict 460
defined 327

Index 543
Embedding (continued) Examples (continued) Fields, types of (continued)
editors 96 password fields 130 color 132
error message 329 replication 444 combobox 127
folders 197 restricting access 389 computed 80, 133
navigators 196, 231 servlets.properties file 309 computed for display 133
objects 327 Excel files computed when composed 133
outlines 216 importing from and exporting to 481 data entry 133
views 196, 197 Exchanging date/time 121
Encapsulated documents 143 field data 338 dialog list 127
Encrypt field 143 Execution Control List. See ECL 300 editable 133
Encryption Expanding embedded elements 142
database 393 sections 387 formula fields 131
default 399 views 183, 505 hidden 83
defined 394 Exponential notation HTML 140
described 392 described 120 list box 127
document 394 Exporting mail-enabling 142
examples 130, 395 files 481 Names 125
field 394, 395 Java applets 300 Numbers 120
levels 393 views 487 password fields 130
views and 398 views as CSV 487 radio button 127
Encryption keys Extended accelerator keys reserved 142, 143, 145, 415
changing 398 enabling 531 rich text 117
creating 396 Extended ACL rich text lite 117
defined 394 described 365 shared 114
distributing 396 External database access text 117
exporting 396 with Domino Connectors 283 time zone 133
fields for 142, 398 with Lotus Enterprise Integrator 283 Fields, working with
listing 398 with ODBC 290 adding to existing documents 415
mailing 396 ExternalData parameter annotating 406
managing 396 in Java applets 302 CGI variables and 528
merging 397 Externalization for Java applets copying 113
password fields and 130 described 302 creating 113, 338
secret 142 default active 135
Entry helper button default values for 120, 134
described 127
ERP systems
F defined 75
deleting 113
federated data 207
connecting to 283 described 113
Field data
Error executing agent disabling field input 134
deleting from documents 113
error message 265 editing 390
exchanging 338
Error handling enabling field input 134
shared fields and reassigning 114
on forms 105 encrypting 394, 395
Field formulas
Error messages examples 339
creating 133
customized forms for 105 exchanging data in 327
described 134
OLE objects and 329 formatting for the Web 139
Field help
Events formulas 134
writing 406
agent 238 hiding 56, 137
Field label
calendar view 238 HTML attached to 139
defined 116
click 238 inheriting documents in 141
Field names
database 238 inheriting values in 140
described 116
described 238 layout regions and 138
requirements for 116
field 238 modifying 266
Field types. See Data types 113
form 238 naming 116
Field values
page 73 recalculating computed 133
calculating 133
programming 238, 250 renaming 116, 415
default for editable fields 134
view 238 replacing field values 266
displaying 173, 415
Examples resizing 138
Fields
access control sections 388 setting input validation formula 134
authors 385
agents 346 setting translation formula 134
DCRs and 288
automating navigators 228 shared resources as 38
described 113
choice list field generation 128 signing 388
enabling for instant messaging 126
customizing window titles 88 testing 409
encrypting 394, 395
encryption 395 Web and 497
in Notes and Web applications 18
exchanging data 339 File field
readers 385
fields 339 described 415
Fields, types of
hiding 335 File formats
category 187
hotspots, text pop-up 248 importing from and exporting to
checkbox 127
inheriting information 140 views 481
choice list fields 127

544 Application Development with Domino Designer 7


File formats (continued) Forms (continued) Formulas (continued)
sharing 38 compared to pages 49, 75 entering in the Script area 3
File resources copying 79 field 133
creating 39 creating 75, 79, 332, 391 input translation 133
opening with URL commands 512 DCRs and 288 input validation 133
shared 39 defaults 54, 77 literalizing 131
File sets deleting 79, 415 named elements and 217
custom 358 described 75 prompting users 100
File upload control designing for Notes and Web 18 Forwarding
described 93 DOLS Offline Configuration 349 documents 344
Files encryption property 394 restricting 390
attaching to documents 61, 93 for replacing dialog boxes 18 Frames
opening with WebDAV 280 headers/footers 83 borders for 147
Flat style outline hiding 80 described 147
described 218 in Notes and Web applications 18 in Web applications 498
Floating point arithmetic layers on 66 naming 148
described 120 naming 80 sizing 149
FolderOptions field 146 replication and 83 specifying a target frame 151
Folders storing 415 Framesets
adding documents to 142 storing with documents 77, 142, 143 content for 148
copying design elements into 36 testing 112, 409 creating 147
copying documents to 266 Web applications 82, 497 defined 11, 147
creating 368 Forms, types of keyboard accessibility and 25
creating bookmarks in 36 anonymous 83 launching automatically 152
creating in a database 36 billing 101 launching on Web 203
default 160 contact printing 101 opening 510
defined 161 customized results forms 518 outlines and 224
described 155 dialog 99 From field 141
embedding 197 Domain Search forms 106
launching into framesets 152 response 85
limiting access 389
MAPI Folder Interface and 491
version tracking 86
Forms, working with
G
getCodeBase
organizing applications 35 choices on 100
in Java applets 304
removing documents from without designing prompts 100
getDocumentBase
deleting 266 dialog boxes as 99
in Java applets 304
security 390 displaying as Web page 510
GIF files. See Graphics 226
shortcut keys 537 displaying documents with forms 77
Global Workbench. See Domino Global
trash 205 displaying without editable
Workbench 27
Web 161 fields 510
Graphical date/time controls
Fonts edit mode 83
described 124
applying to text 52 embedded controls on 93
Graphics
changing in a form 54 embedded editors on 96
adding an editor to Designer 277
in view applet 200 embedded navigators and 231
adding to navigators 226
Footers embedding objects in 327
adding to outline entries 217
creating 83 examples 339
alternate text for 25
Foreign language applications field-exchange in 327
backgrounds 60
designing for 27 improving performance of 111
bitmap 59
Foreign symbols launching an OLE object 333
changing 60
translating 481 linking objects in 327
changing when moused over 43
Form access list navigators and 199
choosing colors for 58
creating 384 objects and 327
copying 226
Form elements OLE and 328
creating 59
listed 75 securing 384, 390, 391, 394
customizing letterheads 41
Form processed confirmation templates and 141
database management and 41
described 105 window titles 88
design tools for 226
overriding 142 Formula fields
dynamic 43
Formatting described 131
importing 226
HTML 139 programming 131
JPEG 59
numbers 171 Formula pop-ups
navigators and 226
text 52 creating 248
pasting 226
Web applications 524 defined 236
PCX 59
Forms deleting 248
shared resources 38
accessing 384 editing 248
text over 138
adding XML to 317 Formulas
TIFF 59
autolaunching 332, 334 automating applications 272
Gray scale
autolaunching objects 333 COL files and 487
blending colors 41
changing 413, 414 columns and 173

Index 545
Grid lines Hotspots Importing (continued)
displaying in views 183 action hotspot 249 Java applets 294
Group calendars button hotspot 246 lines per page 482
in Web applications 496 creating 227 navigators 232
Group names defined 11, 227 Indenting
ACL 372 examples 236 response documents 188
Guides. See Navigators, Outlines 213 imagemaps and 233 Indexes
navigators and 227 updating 463
pop-ups 248 Indexes, full-text
H Web applications and 499
HTML
updating 463
Info field
Handheld devices
adding 63 described 415
designing for 23
adding an editor to Designer 277 Inheriting
Headers
attributes 139, 297 creating fields for 140
creating 83
core attributes 24 documents in fields 141
Headlines database
defined 316 field values 134
described 131
displaying information with Print related documents 85
subscriptions and 37
statement 269 subjects in a response hierarchy 141
Help
formatting 139 Input Enabled property
context-sensitive 405
generating for hidden fields 83 enabling field input 134
databases 407
on pages and forms 63 Input forms
for fields 406
passing to server 142 described 98
forms 407
referencing objects with JavaScript 24 Input translation formulas
overview 404
tag attributes 24 defined 134
Hide-when conditions
viewing frameset source 147 settings for field 134
CGI fields and 528
XML and 315 Input validation formulas
columns and 172
HTML editor defined 134
field settings 137
using 63 Instant messaging
options, setting 23
HTML field 140 adding to an application 47
Web use and 512
HttpSession instance 309 enabling for fields 126
Hide-when fields
enabling in views 171
in Notes and Web applications 18
International characters
Hiding
automated components 275 I displaying on Web 118
in Web applications 498
button hotspots 246 Icon buttons
Internet
columns 183 customizing 37
SSL security and 381
databases 432 Icons
Italic text
design elements 23, 432 creating database 403
in Web applications 118
designs 33, 431 custom icons in views 178
documents 335 displaying in columns 178
elements from mobile clients 23 download 349
examples 335 identity 359 J
fields 56, 137 Image files JAR files
formula pop-ups 248 described 517 described 294
Java applets 297 Image resources Java
menu choices 230 creating 41 Web applications and 25
objects 337 customizing letterheads 41 Java agents
outline entries 217 deleting 41 restricting 368
paragraphs 137 described 38 Java applet properties
section titles 387 dynamic graphic 43 CodeBase 297
servlet names 309 opening with URL commands 512 CORBA classes 297
subforms 89 renaming 41 CORBA SSL security 297
text pop-ups 248 Image set DocBase 297
views 203, 230 described 43 Size 297
Hierarchical names Imagemaps Java applets
displaying as common name 125 compared to outlines and adding to an application 293
Hierarchy. See Response documents 85 navigators 213 alternate text for 25
Home pages described 233 compared to servlets 307
creating 49 Images. See Graphics 59 copying 299
defined 52 Imperial measurement debugging 304
launching 52 described 120 deleting 299
specifying 407 Importing described 293
URLs 407 column format 481 Domino 25
Horizontal rules documents 481 enabling on workstation 294
creating 54 files into views 481, 487 exporting 300
in Web applications 499 foreign characters and symbols into hiding 297
Host forms views 481 importing 294
described 99 graphics 226 linking to 295

546 Application Development with Domino Designer 7


Java applets (continued) Launching (continued) Locks
pages and 61 target frames and 151 document 45
parameters 295 views or folders into framesets 152 Log file
persistence for 302 Layer tree replication events 459
refreshing 300 hiding layers 66 Login
running 296 Layers argument 522
security 300 anchors 66 Login command
selecting 299 background color 69 described 505
serialization 302 content 66 URL guidelines 503
setting HTML attributes 297 copying 66 Logout command
shared resources 38, 298 creating 66 described 505
starting 299 deleting 66 Lookups
stopping 299 hiding 66 creating 100
storing files for 293 HTML properties 69 in multiple Domino Directories 491
troubleshooting 304 Layer Tree dialog box 66 name 125
Java compiler 309 position properties 67 Lotus Instant Messaging
Java Debug Console tile patterns 69 embedding a contact list 63
described 304 Layout regions Lotus Translation Components
Java programs changing 92 Domino Translation Object 29
editing and the Reference tab 3 defined 91 Translation Services Gateway 29
restricting use in agents 257 described 91 LotusScript
servlets 307 fields on 138 application automation 269
storing 38 read access 23 debugger 261
using for data access 283 unsupported features 127 OLE and 327
Java servlets LDAP directories restricted operations in agents 270
XML 323 authenticating Web users with 373 restricting use in agents 257
JavaScript Legacy applications storing programs 38
automating applications with 273 XML and 315 using for data access 283
editing, and the Reference tab 3 Legacy databases Web and 496
table of supported objects 273 connecting to 283 LotusScript agents
JavaScript code Legend restricting 368
passing 142 embedded scheduler 93 LotusScript browser window 3
JavaScript header LEI LotusXSL Processor
for pages and forms 73 described 283 downloading 323
JDBC Letterhead LS:DO
using for data access 283 customizing 41 using for data access 283
JPEG files. See Graphics 59 Levels. See Response documents 85
Limits
size 30 M
K Linking
databases 423
Macros. See Agents 237
Keyboard shortcuts. See Shortcut Mail
design elements 424
keys 532 agents 346
designs 423
Keys, encryption. See Encryption applications 343
documents 344
keys 142 automating 344
mail 344
Keywords changing default font of 54
objects 327
COL files and 485 customizing letterhead 41
templates and 423, 424
delivery 491, 492
Links
fields 142, 143
creating on Web 118
L database 423
fields for automatic 143
forwarding 344
Labels defined 236
linking 344
fields 116 displaying in views 172
MAPI classes and methods 493
Language preference launching automatically 418
sending 344
setting 27 sending 344
workflow applications 343
setting for Web applications 524 target frames and 151
Mail queue 491
Languages URL 57
Mail router 492
sort order 363 Links field
Mail Send dialog box 143
Launching described 415
Mail-in Database
databases 418 List box fields
agents and 346
databases into framesets 152 aliases in 129
creating 345
documents 404 Lists of choices
Mail-in Database documents
documents or pages into displaying 100
described 345
framesets 152 LocalDomainServers group
MailFormat field 143
home pages 52 access level 372
MailOptions field 143
links 418 Locking
Main class name
objects 327 WebDAV and 282
described 294
pages 418

Index 547
Manager access Navigator templates Numbers
actions 366 forms as 199 columns for 171
privileges 368 Navigators formatting in Number fields 120
MAPI. See Messaging application progam accessibility of 224
interface (MAPI) 491 actions in 224
Master design copies
creating 408
adding objects to 224
color 227
O
Object parameter
Menu bar creating 225
in Java applets 302
described 3 designing 224
Objects
Menus displaying 230
drawing 226
actions 240 editing 225
embedding 327
displaying 328 embedding 231
enhancing 227
hiding choices 230 examples 228
hiding 337
shortcut keys 274 formulas and 228
hotspot 227
Messaging graphics and 226
launching 327, 332, 335
adding Sametime to an highlighting 227
linking 327
application 47 hotspots and 227
referencing with JavaScript 24
Messaging application program interface imagemaps and 233
resizing 330
(MAPI) importing 232
updating 331
Address Book provider 491 opening 230
viewing properties and events of 3
classes and methods 493 programming 224
Objects tab 3
Message Store provider 491 renaming 413
OCX. See Custom controls 327
Message Transport provider 492 scripts and 228
ODBC
platforms 492 styling 227
connecting to 287
requirements 492 templates and 199, 231
data sources 290
service providers 491, 492 testing 232
Datalens and 290
spooler 492 text on 227
described 283
Metadata Web 199, 224, 499
using 290
passing 142 No access
views 291
Metric measurement assigning 366
Offline Subscription Configuration profile
described 120 privileges 368
document
Microsoft files Note ID
creating 351
importing from and exporting to 481 finding documents by 466
editing 349, 351
Microsoft Internet Information Server Notes
Offline subscriptions
(MIIS) 503 hiding views 203
overview 349
Microsoft Office Library template Notes applications
OLE
described 479 planning 17
actions and 337
Mobile applications running on Web 17
applications 327
designing 23 Notes Browser
autolaunching objects 334
hiding elements from 23 previewing in 46
automating 337
Multilingual applications Notes classes
connecting to 287
designing for 27 setting up applet access to 300
custom controls 327
URL commands 527 Notes client
exchanging data 338
Web applications and 22, 140
launch properties 333
Notes/FX
launching in-place 334
N enabling 339
Web applications 497
LotusScript 327
Named elements property sheets and 330
NOTES.INI file
formulas for 217 publishing actions using 337
recording debugging information 264
Names resizing 330
NotesFlow
displaying 125 Web and 327
actions 327
entering from a list 125 OLE custom controls. See Custom
applications 327
Names dialog box controls 327
field-exchange 327
displaying 125 OLE DB
NotesFX
Names fields connecting to 287
using 338
described 125 OLE objects
NotesLog class debugging
enabling for instant messaging 126 autolaunching 333
setting up 265
in Web applications 497 debugging 329
NSF files
Naming launching 335
creating 34
ACL entries 373 opening with URL commands 517
NTF files
categories 187 Online chat
creating 411
forms 80 adding to an application 47
defined 31, 419
frames 148 Online status
Designer 479
framesets 147 displaying in views 171
Number fields
Navigating enabling for fields 126
described 120
Web sites 196, 231 OpenAbout command
Numbering
Navigation described 505
documents 173
in Notes and Web applications 18

548 Application Development with Domino Designer 7


OpenAgent command Pages (continued) Printing (continued)
described 510 creating 50 hidden information 23, 137
OpenDatabase command deleting 50 restricting 390
described 505 described 49 Private agents
OpenDocument command displaying 51 controlling 257
described 512 elements on 49 Web users and 257
OpenElement command embedding controls on 62 Private keys. See Encryption keys 394
described 517 events for 73 Privileges
OpenFileResource command fonts in, changing 54 access level 368
described 512 graphics on 59 Profile documents
OpenForm command HTML and 63 creating 98
described 510 Java applets and 61 defined 97
SearchDomain and 518 JavaScript and 22 Profile forms. See Profile documents 98
SpecialAction argument and 522 launching 418 Profiling
OpenFrameset command launching into framesets 152 agents 262
described 510 layers on 66 Web services 262
OpenHelp command links and 57 Programmable tables
described 505 opening 515 described 54
OpenIcon command programming 73 Programming
described 505 styling text in 52 columns 173
OpenImageResource command Palettes navigators 224
described 512 blending colors 41 Perl script in Web applications 528
OpenPage command choosing colors 58 tables 54
described 515 Panes views 505
OpenServer command shortcut keys 537 Programs
described 505 Password fields creating for events 250
OpenView command described 130 Prompts
described 505 Passwords creating 100
optional arguments 505 URL commands and 522 Properties
Ordered lists PCX files. See Graphics 59 action hotspots 249
in Web applications 498 Percentage changing 417
OtherDomainServers group calculating 183 changing database and design
access level 372 formatting numbers as 120 element 417
Outline applet Performance for Java applets 297
described 25 computed fields and 133 setting for OLE objects 330
using 223 forms and 111 Properties boxes
Outline entries lookups and 128 shortcut keys 534
adding graphics to 217 Web 22 Property sheets
customizing 216 Perl script using with OLE objects 330
customizing twisties 45 Web applications and 528 Protecting
described 214 Persistence design elements 429
displaying as a hierarchy 218 Java applets 302 designs 429
hiding 217 session 309 Proxy settings
named elements and 217 Personal Address Book for previewing in browsers 46
styles for 218 using to enter names 128 Public access
Outlines Personal agents. See Private agents 236 agents 391
accessibility of 214 Pictures. See Graphics 59 assigning 368
creating 214 Pop-up calendar controls 496 defined 391
described 10 Pop-ups documents 391
displaying in framesets 224 creating 248 forms 391
embedding 216 Precision framesets and 147
imagemaps and 213 in Number fields 120 outlines 216
public access for 217 Predefined fields style sheets 391
styles for 218 list of 142 views 391
using aliases with 214 PreFormat Public documents
Overriding described 505 access to 368
default form selection 77 Preview buttons creating 391
Form processed confirmation 105, described 3 Public keys
142 Previewing document encryption 394
proxy settings for previewing 46 applications 46 PublicAccess field 391
databases 418 Purge interval
documents 418 deletion stubs and 440
P framesets 147
hiding information during 137
Pages
adding XML to 317
setting up 46
Printing
R
backgrounds for 60 Radio button fields
headers and footers 83
compared to forms 49 described 127

Index 549
RANGE statement Replication Response hierarchy
described 485 CD-ROM updates 442 creating 85
Read access commands 438, 447 Restricted LotusScript/Java operations
restricting 390 customizing 439 in agents 270
Read access list database design and 467 Restricting
described 390 disabling 442, 446, 468 copying 390
forms 390 document size and 440 design changes 408
Reader access editing conflicts and 469 editing 384
actions 366 enabling 446 forwarding 390
privileges 368 encryption and 438 printing 390
Readers field enforcing consistent ACL 379 RestrictToCategory
creating 385 examples 444 OpenView and 505
updating 386 forcing 447 ReadViewEntries and 505
Readers fields forms and 83 ReturnReceipt field 143
checking 415 history 458 Review requests
creating 384 log file 459 in workflow applications 479
ReadExternalData parameter monitoring 458 Revision tracking
in Java applets 302 non-document elements 440 described 86
ReadForm command planning 438 Revisions field
described 510 purge interval for 440 described 415
ReadViewEntries selective 440 Rich text fields
described 505 settings 438, 439, 443 described 117
Records specifying dates 440 on Web 118
importing 289 templates and 429 Rich text lite fields
Redesigning troubleshooting 466, 468, 469 described 117
forms 414 Web applications 357 Roles
templates 420 WebDAV and 282 assigning in ACL 370
Redirect command Replication conflicts creating 370
described 505 merging 83 Rounding
domain search and 518 Replication formulas in Number fields 120
Reference list using 440 Route. See Navigators, Outlines 213
using 133 Replication history Routing
Reference tab 3 clearing 458 automatic 343
Refreshing displaying 458 Rows
choice list field values 135 specifying dates 440 spacing 183
defined 426 Replication or save conflicts styling 183
designs 426 consolidating 83, 460
field values 133 described 460
Java applets 300
Relational databases
preventing 460
Replication priority
S
Sametime
accessing with ODBC 290 assigning 442
adding to an application 47
connecting to 283 Replies
enabling for fields 126
Renaming automating 346
enabling in views 171
agents 413 Reserved fields
Save conflicts
databases 413 $Anonymous 386
consolidating 460
fields 116, 415 $PublicAccess 391
described 460
forms 413 $UpdatedBy 386
SaveDocument command
navigators 413 $VersionOpt 145
described 512
shared fields 114 billing 101
SaveOptions field 143
views 413 Categories 142
Schedules
Replace Design command contact printing 101
coordinating 93
defined 428 FolderOptions 142, 146
Scientific notation
Replica IDs HTML 142
described 120
assigning access by 373 list of 142, 143, 145, 415
Screen-reader software
Replica stubs SecretEncryptionKeys 142
designing for 25
defined 468 Reserved form names
Script area 3
troubleshooting 468 for navigator or view templates 199
Script libraries
Replicas Resources. See Shared resources 38
defined 38
conflicts 83, 460 Response documents
Scripts
controlling changes 373 columns for 189
creating 250
copying to servers 435 creating 85
deleting 250
creating 438 described 85
Search forms
deletion stubs in 469 indenting 188
described 106
deletions 440, 469 inheriting subject 141
Search results
limiting content 440, 443 Response forms
displaying 518
settings for 438 described 85
navigating 106, 521
size of 467 testing 112

550 Application Development with Domino Designer 7


SearchDomain command Service providers Signatures
described 518 installing 492 attaching to documents 401
SearchEntry command Servlet API 309 defined 388
described 518 Servlet classes storing 400
SearchFuzzy command loading 309 Signing
described 518 Servlet manager 309 documents 401
Searching Servlets Simple actions
domains 518 compared to agents and CGI defined 235
URL commands and 518 programs 307 table of 266
SearchSite command security for 307 Simple agents. See Agents 237
count parameter 518 WebSphere and 21 Single Copy Templates
described 518 XML 323 described 420
optional arguments 518 servlets.properties file Site map. See Navigators, Outlines 213
start parameter 518 example 309 Size
SearchView command sessdata.ser 309 attachments 440
count parameter 518 Sessions database 437, 454
examples and syntax 518 tracking 309 replica 440, 467
optional arguments 518 SGML Size property
start parameter 518 defined 316 for Java applets 297
Secret encryption keys. See Encryption Shared actions SmartIcons
keys 142 creating 244 toolbar 37
Sections defined 236 Sort order
access to 387 editing 244 columns 182
collapsing 387 inserting 244 in subscriptions 363
creating 56, 387 Shared agents SpecialAction argument
defined 75 controlling 257 described 522
editors and 387 defined 237 SSL
hiding titles 387 Shared databases creating user certificates 522
signing 401 described 343 Internet security and 381
Secure Sockets Layer. See SSL 522 Shared fields server certificate request 522
Security converting 113, 114 URL commands and 522
agents 257, 307 copying 113 Start parameter
CGI programs 307, 528 creating 114 search results and 521
database 378 deleting 114 Statlog task
database encryption 393 inserting 114 database activity reporting 461
decrypting data 398 multilingual 114 statistics 462
described 365 renaming 114 user activity reporting 463
documents 383 stored forms and 77 Status tracking
electronic signatures 401 Shared graphics. See Image resources 41 described 189
encryption 392 Shared resources Stop Java applet
folders 390 across databases 38 described 299
for automation 272 deleting 40 Storing
for Notes and Web applications 18 described 38 files for Java applets 293
hidden fields and 137 exporting 40 forms with documents 77, 142, 143
Java applet access to Notes files 39 Java code 38
classes 300 for Java applets 298 LotusScript programs 38
servlets 307, 309 non-NSF files as 38 programs 307
signatures and 400 refreshing 40 Structured text files
SSL certificates 522 Shortcut keys defined 483
URL commands and 522 cursor 536 exporting to 487
SendTo field 143 databases 533 importing into views 483
Server certificate request defined 531 Style editor applet. See Editor applet 25
creating 522 Designer 532 Style sheets
Server commands dialog boxes 533 public access 391
OpenServer 505 documents 534 XSL 317
Redirect 505 enabling 531 Style sheets, cascading. See CSS 24
Server tasks folders 537 Styles
Designer 31 form names 80 CSS 24
ServerRequest command menu choices 274 Stylesheets
examples 522 panes 537 DXL 313
fields 522 properties boxes 534 Styling
syntax 522 text 535 columns 183
Servers text properties 536 frames 149
access levels for 366 tools 277 horizontal rules 54
console commands 263 views 537 navigators 227
restricting creation of databases Sign field 143 rows 183
on 257 titles 168

Index 551
Styling (continued) Templates (continued) Tracking (continued)
views 183 replication and 425, 429 server usage 101
Subforms server 31 sessions 309
creating 89 Single Copy 420 unread documents 190
defined 38, 75 unlinking 429 versions 86, 145
described 89 unlinking design elements from 429 TranslateForm argument
examples 89 updating databases with 424 described 522
inserting 89 Terminations group Translation
layers on 66 adding names to 373 applications 27, 129
securing 384, 390, 391, 394 Testing Domino Global Workbench 27
Subject field 141 applications 412 foreign symbols and characters 481
Submit button design 409 Translation formulas
on Web 22 forms 112, 409 defined 133
SubmitCert command navigators 232 setting for fields 134
examples and syntax 522 response forms 112 Trash folders
fields 522 views 410 creating 205
Subscription documents Text designing 205
storing 131 computed 53 in Web applications 205
Subscription forms fields 117 Tree style outline
creating 37 graphics with 138 described 218
Subscriptions navigators and 227 Troubleshooting
described 131 styling 52 agents 261
enabling 37 Web 500 calendar views 193
Subscriptions, offline Text files database access 464
overview 349 exporting 487 database design changes 467
Symbols importing to a view 482, 483 database performance 464
currency 120 Text pop-ups documents in log file 466
Symphony files creating 248 fields 415
importing into views 482 defined 236 framesets 152
Synopsis. See Design synopsis 413 deleting 248 Java applets 304
System actions editing 248 OLE object error 329
creating 240 Text properties replication 466, 468, 469
shortcut keys 536 Truncation
Thousands separator in imported text 482
T setting 120
TIFF files. See Graphics 59
Twisties
customizing 45
Tab order
Time
specifying for fields 135
displaying 170
Tabbed tables
described 54
entering 121
formatting 121, 170
U
Tables Underline
formula language 123
creating 49 in Web applications 118
ranges 121
in editor applet 498 Unlinking
Time controls
in Web applications 499 design elements 429
creating 124
programmable 54 templates and databases 429
in Web applications 496
Tabular text files Unread marks
Time zones
COL files and 486, 487 color 190
fields 133
defined 482 displaying 190
setting for Domino Off-Line Services
exporting to 487 Domino 5 users and 190
subscriptions 363
importing into views 482, 487 UpdatedBy field
setting for Web applications 524
Target frames described 415
Title field
order of precedence 151 tracking edits 386
described 77, 415
specifying 151 Updating
Titles
TeamRoom template designs 426
database 31
described 479 documents 414
frameset 147
Templates Java applet files 38
window 88
agents and 420 objects 331
Toolbars
changing 419, 425 Upgrading
customizing 37
customizing 420 framesets and 147
Tools
defined 31, 419 Java applets and 293
customizing 277
design changes and 31 URL commands
organizing on the Tools menu 278
Designer 479 authentication and 522
shortcut keys 277
fields in 141 count parameters 518
Totals
linking to 423, 424 explicit 514
calculating 183
master 31 for opening resources 512
Tracking
navigator 231 for setting user preferences 524
document status 189
redesigning 420 for Web applications 48, 503
editors 386
replacing design and 428 guidelines 503

552 Application Development with Domino Designer 7


URL commands (continued)
home page 407
Views (continued)
calendar 155, 157, 193
W
implicit 514 categories and 186 Web
opening documents by key 514 character translation file (.CLS) @commands and 22
searching and 518 and 481 @functions 495
server commands 505 COL files and 487 access levels 366
ServerRequest 522 collapsing 183 actions 496
start parameters 518 columns in 9 agents 496
syntax 503 compatibility 172 authentication and 373, 522
XML and 505 copying 159, 160 CGI variables 528
URL links creating 159, 368 creating forms for 497
pages and 57 creating trash folder 205 displaying views 196
URLs customizing twisties 45 documents 80
generating 503 database performance and 465 example of agents 256
servlet 307 default 160, 190 fields and 497
User activity defined 9, 155 file attachments on 93
reporting 463 defining columns 167 folders 161
statistics 461 deleting 159, 160 hidden fields and 83
User names designing 159 hiding design elements 432
aliases 373 displaying grid lines 183 hiding views 203
Web 382 displaying on the Web 196 improving performance on 22
wildcards in 373 displaying with XML 319 LotusScript and 496
User preferences documents and 163 mailing features 345
setting for Web applications 524 Domino 5 users and 190 navigating 196, 231
User types embedding 196, 197 navigators 199, 224, 499
assigning to ACL 378 enabling for instant messaging 171 Notes/FX and 327
Users encrypted data and 398 Perl script 528
access levels 365 entering names from columns in 128 previewing requirements for 46
terminated 373 exporting 481, 487 selecting documents in views 203
Using Database document hide-when formulas and 172 Server document and 407
creating 404 hiding 203, 230 tables 499
inheriting from template 420 hierarchy in 85 text 500
opening 505 icons in 178 unsupported features 124, 125, 495
importing 481 views 500
importing tabular text into 482 Web applications
color for 22
V in Notes and Web applications 18
indenting in 85 designing 22
Values displaying text in 52
launching into framesets 152
recalculating for computed fields 133 enabling for offline use 349
launching on Web 203
refreshing 135 home pages for 52
limiting access 389
Version control Notes client and 31, 118
lookups in 100
conflict documents as 83 planning 17, 21
mapping imported columns to
field for 142 programming 503
fields 484
forms for 86, 145 replacing dialog boxes 18
OBDC access 291
tracking 86, 145 replicating 357
programming 163
VersionOpt field 145 running on Notes 17
public access 391
View applet URL commands 48, 503, 512
renaming 413
described 25, 200 Web control page
searching 518
font support 200 Domino Off-Line Services 349, 350
selecting documents to include
view properties and 501 Web elements
in 163
View indexes date picker 62
setting design for documents in 77
updating 463 embedding on pages 62
shortcut keys 537
View lookups Web links
single category 198
choice list aliases and 129 displaying in views 172
specifying field types of imported
choice list fields and 128 Web pages
columns 484
Names fields and 125 home pages 52
styling 183
View menu in frames 148
switching 183
working with framesets and 147 Web services, working with
testing 410
View templates profiling 262
troubleshooting 193
defined 196 Web users
types of 155, 207
forms as 199 access to forms 82
unread marks 190
Views access to outlines 223
updating 463
accessibility of icons in 178 attaching files 93
URL commands and 505
adding background images 183 authenticating 373
Web 500
adding trash folder 205 controlling access 381, 382
Vision-impaired users
aliases and 129 designing for Notes and 140
designing for 25
allowing document selection on Domino applets for 25
Web 203

Index 553
WebDAV Work area, Designer XML (continued)
configuring 278 described 3 exporting 324
described 277 Workflow formatting with style sheets 317
editing databases with 278 applications 327, 343, 479 generating with an agent 321
replication and 282 defined 343 HTML and 315
WebQueryOpen events features 344 in Domino applications 315
agents and 307 overview 343 Java servlets 323
described 256 Worksheet files tags 315
WebQuerySave events COL files and 484, 485 terminology 316
agents and 307 exporting to 487 transforming 324
described 256 importing into views 482 viewing 324
WebSphere WriteExternalData parameter XSL
integrating with 21 in Java applets 302 style sheets 313
Width WriteObject parameter XML 317
columns 183 in Java applets 302 XSLT
Window tabs defined 316
described 3
Window titles X
described 88
WindowTitle field
XML Z
adding to forms and pages 317 ZIP files
described 415
adding to views 319 described 294
WKSCOL statement
cascading style sheets and 315
described 485
defined 313, 316

554 Application Development with Domino Designer 7


Notices

This information was developed for products and services offered in the USA. IBM may not offer the
products, services, or features discussed in this document in all countries. Consult your local IBM
representative for information on the products and services currently available in your area. Any reference
to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country/region or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other country/region where such
provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR
FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore,
this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication. IBM
may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part
of the materials for this IBM product, and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information that has been exchanged, should contact:
Lotus Software
IBM Software Group
One Rogers Street
Cambridge, MA 02142
USA
Such information may be available, subject to appropriate terms and conditions, including in some cases
payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or by
any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems, and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements, or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility, or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
Trademarks

IBM, the IBM logo, AIX, DB2, Domino, Freelance, Freelance Graphics, iSeries, i5/OS, Lotus, Lotus Notes,
LotusScript, Notes, 1-2-3, OS/400, Quickplace, S/390, Sametime, SmartSuite, WebSphere, z/OS, and
zSeries are trademarks or registered trademarks of IBM Corporation in the United States, other countries,
or both.
Additional IBM copyright information can be found at: http://www.ibm.com/legal/copytrade.shtml

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

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

Intel and Pentium are trademarks of Intel Corporation in the United States, other countries, or both.

The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a
Service Mark property of CompuServe Incorporated.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product and service names may be trademarks or service marks of others.

Você também pode gostar